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(57) Abrege 

Cette invention se rapporte d un adaptateur de messagerie g6n6ral entre interface program matique et rfeeau, qui permet 
d'exposer una interface d'integration d'objet ou une interface de programmation d'application appropriees a des applications sur 
un dispositif contr6leur et d'envoyer des messages de donnees de reseau pour requerir des services ou un etat de demande d'un 
dispositif command^. Get adaptateur convertit par mappage les appels d'application adresses a I'interface en messages de donnees 
reseau en fonction de protocoles de service du dispositif command^. Get adaptateur g6n6ral fournit interface appropri^e ^ 
n'importe quel sendee specifique d'un dispositif commande sur la base d'une description de donnees de Tinterface et convertit 
les appels d'application en messages de donnees reseau sur la base d'une description de donnees d'un protocole et d'un forrnat 
pour les messages de donnees reseau, en vue de leur interaction avec le service specifique. Une fois obtenue la description 
d'interface/messagerie, les applications sur le dispositif contrfileur peuvent interagir en mode programmatique avec {'adaptateur, 
et celui-ci g6re les echanges de messages appropries avec le service du dispositif commande. Get adaptateur general permet 
d'effectuer des operations d'ecriture dans les applications du dispositif contrdleur en utilisant une programmation orientee 
objet tout en evitant le te!6chargement de codes. 
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DATA DRIVEN REMOTE DEVICE CONTROL MODEL WITH GENERAL 
PROGRAMMING INTERFACE-TO-NETWGRK MESSAGING ADAPTER 



TECHNICAL FIELD 

Y5 This invention relates generally to dynamic configuration of interconriectivity 

5 among distributed devices and services, and more particularly relates to providing a 
capability to access device- or service-specific operational information and perform 
remote automation and control of embedded computing devices using a data-driven 
remote programming model, such as in a pervasive computing environment 



BACKGROUND AND SUMMARY 

10 The cost of computing and networking technologies have fallen to the point 

where computing and networking capabilities can be built into the design of many 
electronic devices in the home, the office and public places. The combination of 
inexpensive and reliable shared networking media with a new class of small computing 
20 devices has created an opportunity for new functionality based mainly on the 

15 connectivity among these devices. This connectivity can be used to remotely control 
devices, to move digital data in the form of audio, video and still images between 
devices, to share information among devices and with the unconstrained World Wide 
Web of the Internet (hereafter "Web") and to exchange structured and secure digital 
data to support things like electronic commerce. The connectivity also enables many 
20 new applications for computing devices, such as proximity -based usage scenarios where 
devices interact based at least in part on geographical or other notions of proximity. A 
prevalent feature of these connectivity scenarios is to provide remote access and control 
of connected devices and services from another device with user interface capabilities 
(e.g., a universal remote controller, handheld computer or digital assistant, cell phones, 
'^5 25 and the like). These developments are occurring at the same time as more people are 

becoming connected to the Internet and as connectivity solutions are falling in price and 
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increasing in speed. These trends arc leading towards a world of ubiquitous and 
pervasive networked computing, where all types of devices are able to effortlessly and 
seaniiessly interconnect and interact. 

In accordance with a new device connectivity architecture known as Universal 
5 Plug and Play, devices and services are controlled by exchanging well-defined XML- 
format data messages. At the programmatic level, on the other hand, it is useful and 
productive to work in an object-oriented framework. 

Prior cormectivit>' models are nol adequate to bridge between object interfaces 
and the data messages exchanged with the controlled device over a network. Some 

10 prior connectivity models require a controlling device to download the program code 
(such as a device driver, Jini code* etc.) for interacting with the controlled device or 
service from a networked source. Such a code download requirement is unsuitable to 
the Web and other ubiquitous computing scenarios. Other connectivity models require 
use of a custom-written object for specific classes of services. Thi.s approach leads to 

1 5 deployment hassles (e.g., user setup and configuration) and also is imsuitable to 
ubiquitous computing. 

In accordance with a technology described herein, a general programmatic 
intcrfacc-to-networic messaging adapter (called a "rchydrator") is a module that exposes 
a suitable object integration interface or application programming interface to 

20 applications on a controller device ond sends network data messages to invoke services 
or quer>' status of a controlled device. The adapter maps application calls to the 
interface into network data messages according to service protocols of the controlled 
device. The described adapter preferably is generic to all devices and services 
compatible with the connectivity model, and adapts itself to specific of the devices 

25 based on an interface and message format/protocol description. In other words, this 
adapter operates as a universal module through which network data message-driven 
services on other networked computing devices can remote programmatic application 
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programming interfaces, including object integration interfaces according to an object 
^0 model such as Microsoft's COM, CORBA, JAVA, and the like. 

More specifically, this general adapter provides the interface suitable to any 
specific service of a controlled device based on a data description of the interface, and 
5 converts the application calls to network data messages based on a data description of a 
protocol and format for network data messages to interact with the specific service. 
Once the inlerface/naessaging description is obtained, applications on the controller 
device can pro grammatically interact with the adapter, and the adapter then handles 
20 appropriate message exchanges with the service of the controlled device. With the 

10 described adapter, no code download is required, only the interface/messaging 

description is needed. The description can be obtained from the controlled device, a 
network server computer, or by pre-loading or caching on the controller device, fhe 
technology allows controller device applications to be written using object-oriented 
programming, while avoiding code download. 
15 Additional features and advantages will be made apparent from the following 

detailed description of the illustrated embodiment w^ich proceeds with reference to the 
accompanying drawings. 
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30 



BRIEF DESCRIPTION OF THE DRAWINGS 

35 Figures 1 and 2 arc block diagrams of a device architecture per Universal Plug 

20 and Play using user control points, controlled devices and bridges for connectivity 
between devices. 

Figure 3 is a block diagram of a device model per Universal Plug and Play. 
Figure 4 is a block diagram illustrating example devices conforming to the 
device model of Figure 3. 
25 Figure 5 is a block diagram illustrating device state synchronization using a state 

table and eventing. 

Figure 6 is a block diagram illimlrating device addressing. 
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25 



Figure 7 is a block diagram of a programmatic interfacc-to-nctwork messaging 
'fO adapter or Rehydrator in the device control model of Figure 3. 

Figure 8 is a general data flow diagram of the Rehydrator of Figure 7 in the 
device control model of Figure 3. 
5 Figure 9 is a block diagram of an implementation design of the Rehydrator of 

15 

Figure 7. 

Figures 10 and 1 1 are block diagrams illustrating an interna} software 
architecture of the user control point and controlled device in the device control model 
20 of Figure 3. 

1 0 Figure 12 is a block diagram illuslrating an internal software architecture uf a 

combined bridge and user control point in the device control model of Figure 3. 

Figure 1 3 is a data flow diagram illustrating a typical browsing protocol 
sequence in the device control model ofFiguit; 3. 

Figure 1 4 is a listing showing a layout of a description document in the device 
1 5 control model of Figure 3. 

Figure 1 5 is a listing of an exemplary icon list of a Description Document in the 
device control model of Figure 3. 

Figure 16 is a listing of an exemplary service control protocol declaration in a 
Descriptioa Document in the device control model of Figure 3. 
20 Figures 17, 18, and 1 9 arc a listing of an exemplary contract in the device 

control model of Figure 3. 

Figures 20 and 21 are a listing of an XMl . schema for a Service Control 
Protocol Declaration Language used in the device control model of Figure 3. 

40 

Figure 22 is a block diagram of an eventing model used in the device control 
25 model of Figure 3. 

Figure 23 is a data flow diagram illustrating subscription, notification and 
45 unsubscription in the eventing model of Figure 22. 
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Figure 24 is a block diagram of a computer system that may be used in the 
device control model of Figure 3. 

Figure 25 is a block diagram of a device having embedded computing and 
networking capability per universal-plug-and-play (UPNP) stemdards that may be used 
5 in combination with the computer system of Figure 24 in tlie device control model of 
Figure 3. 

Figure 26 is a block diagram of a software architecture per UPNP standards in 
the embedded computing device of Figure 25 

Figure 27 is a data flow diagram of a process for automatic network introduction 
1 0 of the embedded computing device of Figure 25 into an ad hoc computer network 
environment per the UPNP protocol. 

Figure 28 is a data flow diagram of a process for automatic network introduction 
of the embedded computing device of Figure 25 into a configured computer network 
environment per the UPNP protocol. 
1 5 Figure 29 is a block diagram of a software architecture of a client device per 

UPNP standards having embedded computing and networking c^ability that may be 
used in the device control model of Figure 3. 

Figure 30 is a block diagram of an exemplary home or office pervasive 
computing environment having a variety of computers as per Figure 24 and embedded 
20 computing devices as per Figure 25 interconnected per UPNP standards that may be 
used in the device control model of Figure 3. 

Figures 3 1 through 43 are program listings of interfaces used in the Rehydrator 
implementation design of Figure 9. 

Figures 44-46 are an XML format listing that depicts an exemplary contract for 
25 interacting with a stock quote Service. 

Figures 47-50 are an XML format listing that depicts an XML schema for 
defining Contracts. 
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DETAILED DESCRIPTION 

The following delailed description is directed toward a general programmatic 
interface-to- network messaging adapter (also known as a "rehydralor") in a device 
control model. In one described implementation, the rehydrator is used in a device 
5 architecture 100 (Figure 1), connectivity model, and device control protocol proposed 

15 

by Microsoft Corporation, called Universal Plug and Play ("UPnP"). Although 
described in the context of a device control model, and specifically UPnP, the general 
programmatic interface-to-network messaging adapter of the invention also is more 
20 generally applicable in other distributed networking environments to provide an object- 

10 oriented or like application programming interface to applications for interacting 
remotely using network data messages. 

25 Universal Plug and Play 

Universal Plug and Play (UPaP) is an open network architecture that is designed 
to enable simple, ad hoc communication among distributed devices and services from 
1 5 many vendors. UPnP leverages Internet technology and can be thought of as an 

extension of the Web model of mobile web browsers talking to fixed web servers to the 
world of peeMo-pecr cormectivity among mobile and fixed devices, UPnP embraces 
the zero configuration mantra of Plug and Play (PnP) but is not a simple extension of 
35 the PnP host/peripheral model. 

20 The cost, size and battery consumption of computing technology—including 

processing, storage and displays—continues to fall. This trend is enabling the evolution 
of stand-alone, single or limited fimction computing devices such as digital cameras, 
audio playback devices, smart mobile phones and handheld computers. Concurrent 
with this, the economical storage and transmission of digital audio, video and still 
25 images is enabling highly flexible models for managing entertainment content. 
^5 While many of these devices arc capable of useful stand-alone operation, 

seamless connectivity with the PC can enhance the value to the customer of both stand- 
alone devices and the PC. Good examples of this synergy ore digital image capture 
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combined with PC image manipulation, storage and email transfer/web publishing and 
information synchronization between a PC and a handheld computer or smart mobile 
phone. 

Since many of these devices, and the PC itself, are mobile, a suitable 
5 communication arcliitecture must enable a highly dynamic connectivity model and must 
enable peer-to-peer operating among arbitrary combinations of devices. 

The Internet has created a widespread awzireness of the value of simple, 
universal communication that is independent of the underlying transmission technology 
and independent of technology from any single vendor, 

1 0 UPnP makes it possible to initiate and control the transfer of bulk data (e.g. 

files) or AA^ data streams from any device on the network, to any device on the 
network, under the control of any device on the network. UPnP enables the ad hoc 
addition or removal of devices on the network, and it enables multiple controlling 
devices to remain in sync with each other. 

15 UPnP reuses existing protocols and technology whenever possible. The 

transition to this highly connected (and connectablc) world will not occur overnight. 
UPnP builds on existing Internet protocols, but accommodates devices that cannot run 
the complete UPnP protocol suite. UPnP provides an architecture that enables legacy 
devices to conmiunicate with UPnP devices. 

20 IP internetworking has been chosen as a UPnP baseline due to its proven ability 

to span different physical media, to enable real world multiple vendor interoperation 
and to achieve synergy with the Intemet and home and of5ce intranets. Internet 
synergy enables applications such as IP telephony, multiple player games, remote 
control of home automation and security, Intemet based electronic commerce, in 

25 addition to simple email and web browsing. UPnP's scope includes remote control of 
devices and bulk data transfer. But, it does not specify AAA streaming formats or 
protocols. 
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UPnP's media independence enables a great deal of flexibility in the packaging 
of products. UPnP enables an AA'^ system to be controlled through an A/C power 
communications technology, while the transmission of A/'W streams among the 
components is analog or digital. One of the controllers of this system could be on the 
5 television, while another is on a PC. and yet another connected via radio or infrared. 

Unlike Plug and Play, Universal Plug and Play is built on top of networking and 
enables ad hoc peer-to-peer connectivity. Networking, in this context, describes a style 
of cotinectivity that enables any networked device to initiate a communication with any 
other networked device, without having established a prior relationship or maintaining a 
10 persistent relauonship between die devices. Networking also allows multiple devices to 
establish one or more connections with a single device, and it allows for a device to be 
capable of both initiating and accepting connections to/from other devices. The PnP, or 
host/peripheral, model is suitable whenever there is a natural persistent relationship 
between two devices (e.g. a keyboard, mouse and display maintain and a persistent 
15 relationship with a host computer). Even though nelworking does not mandate low 

level persistent relationships, it provides the needed anchors (addresses) for applications 
to choose to maintain associations as a convenience for the customer (e.g. remembering 
commonly used networked printers). 

In order to achieve multiple vendor peer-to-peer interoperation among devices, 
20 vendors desirably agree on common technology' and standards up to the highest level of 
desired functional interoperation. 

UPnP leverages formal protocol contracts to enable peer-to-peer interoperation. 
Protocols contracts enable real-world multiple-vendor interoperation. 

UPnP enables devices to expose a user interface by leveraging browser 
25 technology. In this context, the browser can be considered to be a very rich remote 
terminal. Current browser technology does not maintain a separation of presentation 
from data, or in the case of devices, control. It is possible to hunt through a page of 
HTML to extract data values, but it is not convenient or robust. UPnP leverages the 
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separation of presentation and data enabled by the use of XML, and it extends this 
technology to the device control domain. 

UPnP provides a device-driven auto-configuration capability that preserves the 
experience that customers have on the web. Today, it is possible lo navigate around the 
5 web without loading programs beyond the browser itself Since UPnP enables the 
browser to be extended to control devices, and because UPnP devices are controlled 
with explicit protocols, the browser must somehow learn how to talk to UPnP devices. 
This learning process is driven entirely from the device itself and is accomplishing 
entirely by uploading an XML document that describes the capabilities of the device. 
10 llie architectural component that enables device-driven aulo-configuration is called the 
Rehydrator. The job of the Rehydrator is to convert between APIs and protocols. 

Since the auto-configuration process itself is driven only by the exchange of 
formatted data, there is very little opportunity for a malicious attack from a hostile piece 
of code. 

15 There are some scenarios where {he web UI model is not sufficient fur a rich 

customer experience. It would not be convenient to have to a web for each light switch 
in a house. To support a rich user interface and to enable the aggregation of devices 
into a single UI, UPnP enables application control in addition to browser control of 
devices. This is achieved simply by enabling applications to call the same Rehydrator 

20 APIs that the browser does. Applications can also directly generate and consiime the 
raw UPnP control protocols, provided they are not interested in the device-driven auto- 
configuration enabled by the Rehydrator. 

UPnP assumes that there will be more than one device with UI that wants to 
control other devices in any given network, and it provides a simple mechanism that 

25 enables thc5w; control points to remain in sync. This mechanism can easily support 
device front panels and wireless remotes that do not run UPnP protocols. The UPnP 
control model is third-party control; any device can transfer bulk data (e.g. files) or AA^ 
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data streams from any device on the networic, to any device on the network, under the 
control of any device on the network. 

Tenninology 

The detailed description that follows uses the terminology defined below. 
5 Module . A component of a device, software program, or system that 

implements some "functionality", which can be embodied as software, hardware, 
firaiware, electronic circuitry, or etc. 

User Control Point . The set of modules that enable commimication with a UPnP 
Controlled Device. User Control Points initiate discovery and communication with 

10 Controlled Devices, and receive Events from Controlled Devices. User Control Points 
arc typically implemented on devices that have a user interface. This user interface is 
used to interact with Controlled Devices over the network. The modules minimally 
include a Discovery Client, a Description Client and a Rehydrator. User Control Points 
may also include Visual Navigation, an Event Subscription Client, Event Sink, a web 

15 browser and an application execution environment. User Control Points can add value 
to the network by aggregating the control of multiple Controlled Devices (the universal 
remote) or they can implement a function as simple as initiating the transfer of data to 
or from a Controlled Device. Examples of devices that could be User Control Points 
arc the personal computer (PC), digital television (DTV), set-top box (STB), handheld 

20 computer and smart mobile phone, and the like. Nothing prevents a single device from 
implementing the functionality of a User Control Point and one or more Controlled 
Devices at the same time. 
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Controlled Device . The set of modules that enable communication with a User 
10 Control Point. Controlled Devices respond to discovery requests, accept incoming 

communications from User Control Points and may send Events to User Control Points. 
Devices that support Controlled Device fimctionality may also support local user 
5 interfaces such as front panel displays or wireless remotes. The modules minimally 
include a Discovery Server, a Description Server and a Control Server. Controlled 
Devices may also include a Presentation (web) Server, Event Subscription Server and 
Event Source. Examples of devices that could be Controlled Devices are the VCR, 
20 DVD player or recorder, hcating/ventilation/air-conditioning equipment (HVAC), 

1 0 lighting controller, audio/video/imaging playback device, handheld computer, smart 
mobile phone and the PC, and the like. Nothing prevents a single device from 
implementing the functionality of a User Control Point and one or more Controlled 
Devices at the same time. 



25 



Bridge . A set of modules that enables Bridged and Legacy Devices to interact 
1 5 with native UPnP devices. The bridge itself exposes a collection of UPnP Controlled 
30 Devices to User Control Points. The Bridge maps between native UPnP Device Control 

Protocols and the underlying protocols exposed by the Bridged and Legacy Devices. 
Optionally, such a device could expose UPnP Controlled Devices to Legacy Devices in 
the manner required by the Legacy Devices. Nothing prevents a single device from 

35 

20 implementing the functionality of a User Control Point, one or more Controlled Devices 
and a Bridge at the same time. 

Service Provider . A module used by a UPnP Bridge tliat translates between 
"^0 UPnP protocols and the protocols used by Bridged and Legacy Devices. No Service 

Providers arc required for communication among native UPnP devices. 

25 Bridged Device . A device that cannot participate in UPnP at the native protocol 

^2 level, either because the device does not have sufficient resources or because the 

underlying media is unsuitable to run TCP and HTTP. Examples of devices that could 
be Bridged Devices are power line-controlled AA^ equipment, light switches, 

50 1 1 
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thermostats, \\Tistwatches and inexpensive toys. Bridged Devices arc UPnP complaint 
and are exposed to other UPnP devices through a UPnP Bridge. 

Legacy Device . Any non-UPnP compliant device that must be exposed to other 
UPnP devices through a UPnP Bridge. 

5 Device Model . The UPnP model of Controlled Devices. The Device Model 

includes the addressing scheme, Description Document, Devices and Services hierarchy 
and the fiinctional description of modules. 

Device Control Protocol (DCP) . A complete set of UPnP protocols and schemas 
used to interact with a UPnP Controlled Device. 

iO Device Definition . The formal definition of a Device Type. A Device Definition 

includes a Device Type Identifier, the fixed elements in the Description Document, the 
required set of Service Definitions in the Root Device, and the hierarchy of required 
Devices and Service Definitions. 

Service Definition . The formal definition of a Service Type. A Service 
1 5 Definition includes a Service Type Identifier, definition of the Service State Table 

(SST), definition of the Service Comniand Set, the Service Control Protocol (SCP) and 
Service Control Protocol Declaration (SCPD). 

Device . In the context of the Device Model, a container for Services. A Device 
generally models a physical entity such as a VCR, but can also represent a logical 
20 entity. A PC emulating the traditional functions of a VCR would be an example of a 
logical device. Devices can contain other Devices. An example would be a TVA^'CR 
packaged into a single physical unit. UPnP enables the association of user interface 
(display icon and root web page) with every Device, including Root Device. 

Root Device . The topmost Device in a hierarchy of nested Devices. A Device 
25 with no nested Devices is always a Root Device. 
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Device Type . A relatively high level classification of Devices with common 
10 functionality. Device Type is intended to enable Devices to be simply and 

automatically grouped for presentation. An example of a Device Type is "VCR". 
Device Types are formally defined in lerms of a required set of Service Definitions of 
5 minimum version that a compliant Device must support. UPnP supports searches for all 

15 

De\'ices of a specified Dexicc Type. 

Device Type Identifier . A unique identifier that identifies a Device Definition. 
This identifier adheres to the format of a Uniform Resource Identifier (URI). See, T. 
2^ Bemers-Lee, R. Ficlding» L. Masinter, "Uniform Resource Identifiers (URI): Generic 

10 Syntax", which can be found at lE'i'F RFC 2396 (August 1998). 

Device Friendly Name . A human readable string that is initialized by vendors at 
25 the time of manufacturer of a Device. Every Device, including Root Devices, has a 

Device Friendly Name. A typical Device Friendly Name will contain manufacturer and 
model information, and is used to enable a more precise identification of a UPnP 
1 5 Device firom the set of discovered Devices. Once identified, the Unique Device Name 

30 

(UDN) can be used to unambiguously identify the same Device in the fiiture. UPnP 
enables Device Friendly Names to be changed by User Control Points. The Device 
Friendly Name should not be used as device identifier. 

35 Unique Device Name (UDN) . The fundamental identifier of a Device. Every 

20 Device, including Root Devices, has exactly one UDN. The UDN is globally unique 
and permanent, even across power cycles and physical location changes. The UDN is 
the only UPnP device identifier guaranteed never to change. UPnP enables searches for 
devices by UDN. 

Description Document . A structured unit of data that is used by a User Control 
25 Point or UPnP Bridge to learn the capabilities of a Controlled Device. Description 
Documents are retrieved (rom the Description Server on a UPnP Controlled Device. 
There is one Description Document for every Root Device that describes the Root 
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Device and all non-Root Devices. Description Documents adhere to XML grammar. 
To support localization, multiple Description Documents can exist. A User Control 
Point requests the preferred localized Description Document by using the standard 
HTTP "accept- language" header. 

5 Service . The fundamental UPnP controllable entity (but not the finest level of 

control). An example of a Service is "Clock". Services are defined with a mandatory 
common base set of functionality. Vendors can extend the base set with proprietary 
extensions provided the base functionality is implemented. Service Definitions are 
versioned and later versions are constrained to be supersets of previous versions. UPnP 

0 enables searches for all Devices that contain a specified Service of Q minimum version. 
This search would fmd all clocks, regardless of their packaging. A search for Device 
Type "Clock" would be used to find only stand-alone clocks. 

Service Type . A classification of Services by their function. 

Service Type Identifier . A unique identifier that identifies a Service Definition. 
5 This identifier adheres to the format of a Uniform Resource Identifier (URI). See, T. 
Bemers-Lee, R. Fielding, L. Masinter. Unifoim Resource Identifiers (URJ): Generic 
Syntax , IETF RFC 2396 (August 1998). 

Service State Table (SST) . A logical table consisting of rows of [ Variable, 
Type, Legal Values^ Default Value, Current Value ] that represents the current electrical, 
:0 mechanical and/or logical state of a Service. SST instances are stored on the Controlled 
Device itself and are the ultimate authority of the state of the Service. All local user 
interface, such as front panels or wireless remotes are required to update the SST on 
UPnP compliant devices. 

SST Definition: 

:5 Service Command Set . A set of Commands that can be invoked on a Service. 

Commands generally result in changes in the Current Value field of one or more rows 
of a SST. Commands are logically represented in the format Command ( Variable = 

14 
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New Value, Variable ~ Mew Value. . . . )• Services must accept or reject the complete set 
10 of changes to a SST. There is a mandatory standard Query Command that is used to 

retrieve the Current Value of any row of a SST. 

Service Command Set Definition: 

15 5 Service Control Protocol (SCP) . The protocol used to invoke Commands 

against a Service and to return results. There is exactly one SCP per Service Definition. 
SCPs adhere to the grammar of SCP XMl. schema. SCPs can be generated by an 
automated tool that accepts a SST Definition and a Command Set Definition as input. 

20 

Service Control Protocol Declaration (SCPD) . A formal representation of the 
1 0 schema of a Service. The SCPD declares the rows of a Service's SST and the 

associated Command Set. SCPDs are uploaded from Controlling Devices in their 
25 Description Documents and enable User Control Points or Bridges to invoke 

Commands on the Service without any prior or persistent knowledge of the capabilities 
(or schema) of the Service. There is exactly one SCPD per Service Definition. SCPDs 
1 5 adhere to XML grammar. SCPDs can be generated by an automated tool that accepts a 
SST Definition and a Command Set Definition as input. 



30 



35 



Event . An unsohcited message generated by a Controlled Device and delivered 
to one or more User Control Points. Events are used to maintain a consistent \iew of 
the state of Service across all interested User Control Points, UPnP leverages the 
20 GENA event architecture (see "Generic Event Notification") to transport event 
messages. All events are delivered using TCP/IP for reliability. 

40 Generic Event Notification (GENA) . An event transport protocol. GENA 

leverages TCP/HTTP as a transport. GENA has been submitted as an Internet Draft to 
the IETF. See, J. Cohen, S. Aggarwal, Y. GoLand, General Event Notification 
25 Architecture Base: Client to Arbiter , IETF Intemet Draft, "draft-cohen-gena-client- 
OO.txt." 
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Simple Service Discovery Protocol (SSDP) . A simple network device discovery 
protocol. UPnP uses SSDP to allow User Control Points to find Controlled Devices and 
Services. SSDP operates in a default, completely automatic multicast UDP/IP based 
mode in addition to a server-based mode that uses TCPAP for registrations and qucr>'. 
Transitions between the default dynamic mode and server-based mode are automatic 
and transparent. SSDP enables every Controlled Device to control the lifetime that its 
Description URL is cached in all User Control Points. This enables a Controlled 
Device to remain visible to User Control Points for a relatively long time (through 
power cycles), in addition to enabling a Controlled Device to appear and disappear very 
quickly, all under the control of the Controlled Device. SSDP and related Multicast and 
Unicast UDP HTTP Messages specifications have been submitted as Internet Drafts to 
the IETF. See, Y. Goland, Multicast and Unicast UDP HTTP Messages , IETF Internet 
Draft, "draft-goland-http-udp-OO.txt" and Y. Goland, T. Cai, P. Leach., Y. Gu, S. 
Albright, Simple Service Discovery Protocol/1.0 , IETF Internet Draft, "draft-cai-ssdp- 
vl-02.txt*' 

Client . In the context of UPnP, Client refers to a module that initiates a 
TCP/HTTP connection to a peer HTTP server. 

Server . In the context of UPnP, Server refers to an HTTP server. This is a 
module that accepts incoming TCP/HTTP connections and cither rctums a web page or 
forwards the payload data to another module. Client and Server describe only the 
direction of initiation of TCP/HTTP connections. There is no relationship between the 
low level concepts of Client and Server and the high level concepts of User Control 
Point and Controlled DesHces. Logically, User Control Points always discover and 
initiate communication with Controlled Devices, but this communication requires Client 
and Server ftmctionality on both sides. 

Ho.stname . A Hostname is the Domain Name System (DNS) or NetBIOS Name 
Service (NBNS) that, when resolved to an IP address, represents a network interface 
that can be used to establish TCP/IP level connectivity to User Control Points, 
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Controlled Devices or Bridges. Hostnames can be used to provide persistent network 
level addressing on a network where IP addresses are dynamically assigned and of 
unknown lifespan or to integrate with an existing managed network. UPnP provides an 
algorithm for seeding a device's hostname from its UDN at manufacturing time. 

5 Uniform Resource Locator (URL) . A format for expressing web addresses. 

URLs minimally contain an identification of the protocol family that the URL is valid 
for, a Hostname, and a path. UPnP uses URLs as addresses whenever the module 
accepting the incoming connection is an HTTP server. 

Description URL . The URL returned from a Controlled Device or Bridge in 
10 response to any UPnP SSDP quer>'. This URL always points to a Description Server on 
the Controlled Device. An HTTP GET can be issued on this URL to retrieve the 
Description Document This URL is valid as an address for the lifetime of the 
Hostname embedded in the URL. 

Discovery Server . The module that runs in a Controlled Device or Bridge that 
1 5 responds to SSDP queries. This Server is unique in that it must support UDP/HTTP 
rather than just TCP/HTTP. 

Discovery Client . The module that runs in a User Control Point that initiates 
SSDP queries. 

Description Server . The module that runs in a Controlled Device or Bridge that 
20 responds to HTTP GETs and returns Description Documents. This service consists of a 
TCP/HTTP server than can retrieve and return a Description Document from persistent 
storage (like a fllesystem). 

Visual Navigation . User Control Point functionality that displays the icons of 
discovered Devices and enables the transfer of control to a browser or application to 
25 interact with the Controlled Device. Tn Windows, Visual Navigation could be 
implemented as a folder of icons. 
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Presentation URL . A URL that can be used by a User Control Point to navigate 
to the Presentation Server of a Controlled Device. This URL is returned in the 
Description Document and is valid as an address for the lifetime of the Hostname 
embedded in the URL. All Devices, including non-Root Devices, can have an 
5 associated Presentation URL. 



15 



Presentation Server. A web server. The module that runs in a Controlled 



Device that responds to HTTP GETs or Presentation URLs and returns user interface 
using web technologies (JavaScript, Jscript®, ECMAScript, VBScript, ActiveXi^, Java 
Applet, etc.). 

1 0 Browser . The Presentation Client. A web browser extended with a Rchydrator. 

Control URL . A URL that can be used by a User Control Point to navigate to 
the Control Server of a Controlled Device or Bridge. This URL is returned in the 
Description Document and is valid as an address for the lifetime of the Hostname 
embedded in the URL. All Services have an associated Control URL- 

30 1 5 Control Server . The module that runs in a Controlled Device or Bridge that 

responds to Commands invoked on a Service by a User Control Point. Commands are 
encoded using the SCP specified in the Service Definition. This service consists of a 
TCP/HTTP server than passes control to the native control logic of a Service, updates 

35 

the SST and generates an event if the SST changes. 

20 Rehydrator . In UPnP, the Control Client. A User Control Point module that 

translates between native operating system APIs and SCPs and events. The Rehydrator 
40 uploads SCPDs from Controlled Devices and Bridges and generates appropriate SCPs 

in response to application API requests to invoke Commands. 

Event Subscription URL . A URL that can be used by a User Control Point to 
25 navigate to the Event Subscription Server of a Controlled Device or Bridge. This URL 
is returned in the Description Document and is valid as an address for the litetime of the 
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Hostname embedded in the URL. All Services have an associated Event Subscription 
URL. 



Event Subscription Server . The module that runs in a Controlled Device or 
Bridge that responds to GENA SUBSCRIBE requests from User Control Points. A 
5 SUBSCRIBE informs the Controlled Device or Bridge of the User Control Polnt*s 
desire to receive future events. This service consists of a TCP/HTTP server that adds 
the User Control Point's Event Sink URL to the list of destinations to be NOTIFY'd 
whenever the SST associated with the Service changes. 

Event Subscription Client . The module that runs in a User Control Point that 
10 sends GENA SUBSCIBE messages to the Event Subscription Server. 

Event Sink URL . A URL, supplied by a User Control Point, that is used as an 
25 address to send event NOTIFYs to. This URL is valid as an address for the lifetime of 

the Hostname embedded in the URL. There is no explicit relationship between Event 
Sink URLs and Subscription Identifiers. 

15 Subscription Identifier (SID) . A header in the GENA NOTIFY message that 

identifies the source of an event In UPnP, the SID can be considered as an alias for the 
Event Source instance. 



Event Sink . The module that runs in a User Control Point that accepts incoming 
GENA event NOTIFYs. This service consists of a TCP/HTTP server that passes the 
20 event information to interested applications running on the User Control Point 

Event Source , The module that runs in a Controlled Device or Bridge that sends 
40 GENA NOTIFYs to the Event Sink Servers of SUBSCRIBES User Control Points. 

Domain Name System (DNS) . A distributed system of servers that locates the 
IP addresses of other computers on a network based on their hierarchical names. 

-^5 25 NetBIOS Name Serv er (NBNS) . A server that locates the IP addresses of other 

computers on a network based on their flat NetBIOS computer names. 
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Multicast DNS (MDNS) . A peer-to-peer translation scheme that does not 
10 require involvement of DNS servers. 

UPnP Technologies Overview 

An ovenpHew of technologies utilized in UPnP follows. 

15 

5 Device Discovery: Simple Service Discovery Protocol (SSDP) 

TCP/TP provides the ability to initiate a connection with a specified application 
running on a specific device, provided both the network address of the device (IP 
address) and the application address (port) are known. General ly» application addresses 
(ports) are standardized and widely known, but the problem of learning the IP address 
1 U of a device remains. 

25 Simple Service Discovery Protocol (SSDP) is a protocol thai enables devices to 

learn of the existence of potential peer devices and the required information (an IP 
address) needed to establish TCP/IP connections to them. The successful result of an 
SSDP search is a Uniform Resource Locator (URL). The Hostname embedded in the 
1 5 URL can be resolved to an IP address that can be used to make a connection to the 
discovered device. The name to address resolution is outside of the functionality of 
SSDP, 

SSDP specifics a default, completely automatic, best-effort multicast UDP- 
based operating mode, in addition to a server mode that uses TCP for registration and 
20 query. Fall-forward to ser\'er mode and fallback to the default dynamic mode can occur 
automatically and transparently as a server is added or removed from a networic. Server 
'^0 mode can be used to reduce network traffic, to implement searches based on location or 

policy and to integrate with a directory system. 

SSDP requires that all devices specify a maximum lifetime that SSDP level 
25 knowledge of the device will remain cached in other network devices. If a device does 
not refresh the cache of other network devices before this interval expires, the device 
will disappear from the network. This interval can be chosen to be larger than a typical 
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power down cycle to enable device visibility to persist for a relatively long time, or a 
smaller interval can be chosea to enable more dynamic visibility coniroL In all cases, 
devices that are abruptly removed from the network will eventually disappear from all 
networked de\.Hces. 

5 In response to an SSDP search, UPnP devices return a Description URL in the 

SSDP Location and optionally the Alternate Location (AL) SSDP headers. An 
example location header is a follows: 

Location: http;//device.local/description/path/descriptioa.xml 
In this example, the device. local is the Hostname of the Controlled Device, and 
1 0 the "description/path/description.xml" element of the URL is the path and name of the 
Description Document on the device. 

Eventinu: Generic Eventing Notification (GEN A) 

Eventing, in the context of UPnP, is the ability for a device to initiate a 

connection at any time to one or more devices that have expressed a desire to receive 
1 5 events from the source device. Events are used to enable synchronization among 

multiple devices organized into a many to one relationship. UPnP events are mainly 

used for asynchronous notifications of state changes. 

TCPAP provides the fundamental support for the connections that carry event 

information. Generic Event Notification (GENA) adds conventions for establishing 
20 relationships between interested devices and an addressing scheme to enable the 

unambiguous delivery of events. GENA leverages HTTP addressing and encapsulation. 

User Control Points, Controlled Devices and Bridges 

With reference now to Figures 1 and 2, UPnP is an application-level distributed 
network architecture where the logical nodes on the network are User Control Points 
25 1 04- 1 05, Controlled Devices 1 06- 1 07 and Bridges 120. These classifications refer to 
ftinctionality rather than physical entities. The functionalit>* of UPnP User Control 
Points 104-105, Controlled Devices 106-107 and Bridges 120 can be packaged into 
physical entities (e.g., multiple function devices 102-103) in any combination. 
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The primary distinction between a User Control Point 104-105 and a Controlled 
Device 106-107 is that the User Control Point is always the communication initiator. 
After the initial communication. User Control Points can receive events from Controlled 
Devices. 

Controlled Devices 106-107 are responsible for storing the state of Services. 
User Control Points are required to synchronize to the state on Controlled Devices and 
to share state directly among themselves. 

User Control Points typically have user interface that is used to access one or 
more Controlled Devices on the network. Controlled Devices only have local user 
interfaces. 

Bridges 1 20 (Figure 2) expose devices that do not expose native UPnP protocols 
as native UPnP Controlled Devices. The Bridge itself looks to other UPnP User 
Control Points like a set of Controlled Devices. 

The following table lists the modules in the User Control Points 104-105 and 
Controlled Devices 106-107, along with their functions. 
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Function 


Module 


Function 


Module 


Initiate discovery of 
Controlled Devices. 


Discovery Client 


Respond to 
discovery requests. 


Discovery Server 


Retrieve Description 
Documents. 


Description Client 


Provide Description 
Documents. 


Description Server 


Display a folder of 
icons per discovered 
Device and allow 
transfer of control to 
a selected device. 


Visual Navigation 
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View user interlace 


Web Browser 


Provide user 


Presentation (web) 


10 


exposed by a 
Controlled Device. 




inteface for remote 
User Control Points. 

■ ■ ■ III! 


Server 




Execute 


Application 
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applications. 


Fxecution 
Environment 








Invoke Commands 


Rehydrator 


Accept incoming 


Control Server plus 


20 


on a Controlled 




Commands in SCPs 


native control logic 


Device by sending 
Service Control 
Protocols in 




and execute them. 
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response to local 
API calls. 










Inform a Controlled 


Event Subscription 


Accept requests for 


Event Subscription 
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Device of a desire to 
receive Events. 


Client 


Events and 
remember them. 


Server 




Receive an Event, 


Event Sink 


Send an Event. 


Event Source 
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Device Model 

The UPnP Device Model 200 shown in Figure 3 is the model of a UPnP 
Controlled Device or Bridge that is emulating native Controlled Devices. The Device 
Model includes the addressing scheme, eventing scheme, Description Document 
5u:hema, Devices and Services schema and hierarchy, and the fimctional description of 
modxiles. The UPnP Device Model extends beyond simple API or a command and 
control protocol defmitions to enable multiple User Control Points to have a consistent 
view of Controlled Devices. This requires that the state of rurming services be formally 
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modeled and that all state changes be visible to User Control Points. Central to the 
distributed UPnP architecture is the rule that Controlled Devices are the ultimate 
authority for the state nf Services running on them. 

Service 

5 The fundamental controllable entity in UPnP is a Service 210-217. Every 

running instance of a Service includes: 

• A Service State Table (SST) 230, which represents the current state of the Service. 

The SST 230 can be used to represent the operational mode of device or to 
act as an information source or sink for structured data or simple files. The SST of a 

1 0 VCR 254 (Figure 4) could represent the current transport mode, tuner channel 

selection, input and output switch selections, audio and video decoding format and 
current timer program. The SST of clock 25 1 (Figure 4) would likely represent the 
current time. The SST of an image rendering device could implement a video 
frame-bufFer that can accept raw pixel information or formatted JPG files. The SST 

15 of an audio or video playback device could implement a transfer buffer or queue of 

material to be played. The SST of PDA could implement a collection of formatted 
data that has changed and needed to be synchronized with another device, in 
addition to a transfer buffer for accepting incoming formatted data. 

The logical structure of a SST published in the Service DeHnitioa, but the 

20 actual storage format of an instance of a SST is entirely up the device. The only 

interaction with a SST is through a formal application level network protocol. 

• A Control Server 232, which accepts incoming Commands expressed in the 
Service's Service Control Protocol (SCP). The Control Server passes the command 
to the Servicers native command processing logic and waits for command 

25 completion. Allien the command is completed successfully, the SST is updated, an 

event is generated, and a successful response is returned to the User Control Point, 
in the event of an illegal command or unsuccessful command, no changes are made 
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to the SST and a failure response is returned. The Command and response sequence 
10 is payioad to a TCP/HTTP request/response. 

• An Event Subscription Server and Event Source 234. The Event Subscription 
Server accepts incoming GENA SUBSCRIBE messages from User Control Points 

5 and adds them to a list of User Control Points interested in SST change events from 

the Service. The Event Source initiates a TCP/HTTP connection to each interested 
User Control Point and sends a GENA NOTIFY each time the Service's DST 
changes. The NOTIFY payioad includes the changed contents of the DST. 
20 •A Control URL that identifies the Control Server. 

1 0 • An Event URL that identifies the Event Subscription Server. 

The formal definition of a Service (Service Definition) includes: 

• The definition of the SST. SST layouts are logically specified in terms of rows of { 
Variable, Type, Legal Values^ Default Value ]. The actual instance of a SST would 
also include a Current Value field in every row, 

1 5 • The definition of the Service Command Set that can be invoked against the 
30 Servicers SST. Commands are logically specified in terms of Command ( Variable 

= New Value, Variable ~ New Value, . ). Tf a Command results in more than a 
single Variable change, the updates are atomic and the Command will fail if it is 
illegal to make the specified change to any one Variable. 

35 

20 • The definition of a structured unit of data called a Service Control Protocol 

Declaration (SCPD). SCPD is used to advertise the layout (schema) of the SST and 
Command Set of the Service to a User Control Point or Bridge. The SCPD enables 
^ the User Control Point to invoke Commands (through the Rehydrator) on the 

Controlled Device without any prior or persistent knowledge of the capabilities of 

25 the device. The SCPD is uploaded from the Controlling E>evice as part of the 

Description Dociiment. An automated tool that accepts the SST definition and 
Command Set definition as inputs can generate the SCPD for a Service. 
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• The definition of a network protocol used to invoke Commands against the SST 
^0 associated with a Service and to remm resiilts. An automated tool that accepts the 

SST definition and Command Set definition as inputs can generate the SCP for a 
Service. The SCP can also be generated from tlic SCPD. The Rehydrator's job is lu 
5 convert SCPDs Into SCPs. The reason for a formal SCP specification is to enable 

the implementation of the Control Server itself and to enable simple pecr-to-peer 
device interoperation using only published protocols. 

• An identifier, called the Service Type Identifier, that identifies a unique Service 
20 Definition. Service Definitions are versioned in controlled manner. Every later 

1 0 version of a Service must be proper superset of the previous version. 

Device 

25 According to the device model 200 shown in Figure 3, a UPnP Device 202-205 

(e.g., multiple function devices 102-103 of Figure 1 and bridged devices 122-123 of 
Figure 2) is a logical container of one or more Services 210-217. Generally a Device 
1 5 represents a physical entity such as a VCR. Typical Services in the VCR Device 

30 example might be "TRANSPORr\ "TUNER", "TIMER" and "CLOCK". While 

Devices are often physical entities, a PC emulating the traditional functions of a VCR 
could also be modeled in the same way as the stand-alone VCR. Devices can contain 
other Devices. An example would be a TVA^CR 250 (Figure 4) packaged into a single 

35 

20 physical unit. A Device (e.g., devices 202-203) may also be a logical container of other 
Devices. The top-most Device in a hierarchy of nested Devices 203-205 is called the 
Root Device 202. A Device with no nested Devices is always a Root Device. 
40 The UPnP Device Model was designed to be general and flexible. It should be 

possible to model an entire Nuclear Power Plant as a single Service or as a deeply 
25 nested hierarchy of Devices and Services. In general, a Service 2 1 0-217 is cohesive sei 
of functions that enables flexible packaging into a varict>' of Devices. Services can be 

45 

versioned independently of Devices. 
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All Devices, including Root Devices belong to one or more Device Types. 
Device Types are intended to enable instances of Devices to be simply aiad 
automatically grouped for presentation. An example of a Device Type is "VCR" 254 
(Figure 4). Dex-ice Types are formally defined in terms of a minimal set of versioned 
Services that a Device of Device Type must support Device Types are not formally 
versioned. Device Type is a relatively high level grouping. A Device of Device Type 
only ensures that minimal set of Services of a minimal version is present. There can be 
other Services, higher versioned Ser\'iccs and Services with vendor extensions present 
on such a Device. 

UPnP enables SSDP level searches for a unique instance of a Device (by UDN), 
all Devices of type Device Type and all Devices that contain at least one Serv ice Type 
of minimum version. The result of an SSDP search is always a URL that pcinte to the 
Description Document contained in the Root Device. In the event that matching Device 
is not the Root Device, the Description Document has a tree of nested Devices that can 
be traversed to find the matching Device. 

Every Device includes: 

• One or more Device Types. 

• One or more Services. 

• Optionally^ one or more Devices. 

• Optionally, a Presentation (web) Server 220-223 that can be used to expose Device 
user interface. Every Presentation Server has an associated Presentation URL. 

• A globally unique identifier called the Unique Device Name (UDN). The UDN is 
the fundamental identifier of an instance of a Device. Every Device, including Root 
Devices, has exactly one UDN. 

Every Root Device 202 also includes the Description Document 226 and 
Description Server 228 for all Devices under and including itself. 

The formal definition of a Device (Device Definition 226) includes: 

• The fixed elements of the Description I>ocument that describe the Device. 
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• The required hierarchy of Devices and Service Definitions. 

There can be many Device Definitions that belong to a single Device Type, 

Device Types 

The formal definition of a Device Type includes: 

• A Device Type Identifier. 

• The required hierarchy of Devices and Service Defmitions of minimum versions. 

Service State Table 

A Service State Table (SST) logically consists of rows of: 
Variable, Type, Legal Values, Default Value, Current Value 
Although entries of the Service State Table in UPnP consist of these five items, the state 
table alternatively can contain fewer or additional items. Generally, each entry will 
minimally consist of a Variable name or identifier, and its current value. 
The following table lists various Types available in UPnP. 
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Type 



String 



Numbl&i 



Boolean 



DateTime 



Description 



A sequence of UNICODE characters. 



A nxunbcr, with no limit on digits; may 
potentially have a leading sign, fractional 
digits, and optionally an exponent. 
Punctuation as in US English. 



TRUE or FALSE. 



Example 



15, 3J4,- 
123.456E+10 



A date in ISO8601 format, with optional time 19941 105T08:15:5 
and optional zone. Fractional seconds may be +03 
as precise as nanoseconds. See, "Data 
elements and interchange formats - 
Information interchange - Representation of 
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dates and limes", which can be found at 
hKp://www.iso.ch/markete/8601 .pdf . 



ByteBlock Aji unstructured sequence of bytes. 



The ByteBlock is esseniially a data buffer. In one use, a variable of this type 
can be \ised to effect transfer of a file from the Controlled Device to tlie User Control 
Point. The file to be transferred is kept in the Service State Table as the current value of 
5 this variable. On a change in the file, the file is transferred to any subscribing User 
Control Point in an event notification. 

The reason for representing Services this way is to ensure that the state of a 
Service is easily available in a common way to multiple Vsct Control Points. 
25 An SS r can be used to represent to current operational mode of device, act as an 

10 information source or sink and/or simply be a repository for commands. The S ST of a 
VCR Service could represent the current transport mode, tuner channel selection, input 
and output switch selections, audio and video decoding format and current timer 

30 

program. Alternatively, the VCR 254 could be represented as a Tran.sport Service 260, 
Tuner Service, I/O Switch Service, AA^ Decoding Configuration Service and 
1 5 Programmable Timer Service 26 1 . 
35 The SST of a clock 251 would likely represent the current time. Additionally an 

alarm clock could include Service Variables to configure the clock. 

The SST of an image rendering device could implement a video frame-buffer 
that can accept raw pixel information or formatted JPG files. The SST of an audio or 
20 video playback device could implement a transfer buffer or queue of material to be 
played. The SST of PDA could implement a collection of formatted data that has 
changed and needed to be synchronized with another device, in addition to a transfer 
buffer for accepting incoming formatted data. 
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User Control Point SynchronizatiOTi 

In accordance with an device state and eventing model illustrated in Figure 5, 
UPnP rules require that every change to an SST generate a corresponding event to 
announce the change to the all interested User Control Points. 

fg 5 Device Addressing 

With reference now to Figure 6, UPnP is built on top of HTTP and leverages the 

native address format of the web. Uniform Resource Locators (URLs). URLs 

minimally contain an identification of the application protocol family ("http**) that Ihe 

20 URL is valid for, a Hostname and a path. In the context of UPnP, the path part of a 

1 0 URL can represent either a fllesystem path or simply an identifier of the local system 

module and context that can process incoming messages. 

While UPnP modules are described as HTTP servers, there is no requirement 

25 

thai implementations be based on actual web servers. In most cases, the job of the 
HTTP server is simply to accept the incoming connection, look at the local destination 

15 part of the address (tlie path) and forward the payload to another module. UPnP 

enables, but does not require, that all HTTP Servers be based on a common software 
implementation or runtime instance. Controlled Devices and Bridges can include a 
TCP port specification as part of a URL to override the default value of 80. 

The successful result of a UPnP SSDP level search is always one or more 

20 Description URLs. These URLs can be used to navigate to the Description Docimient 
of a Controlled Device or Bridge. A User Control Point uploads the Description 
Document and extracts the URLs of the Servers nmning on the Controlled Device or 
Bridge. 

40 * 

All URLs returned in the Description Document have a lifetime equal to the 
25 lifetime of the Hostname embedded in them. User Control Points can store these URLs 
as addresses without going through a search sequence first. Once they have been 
45 advertised in a Description Document. Controlled Device and Bridges cannot arbitrarily 

change Server URLs. 



50 



30 



55 



wo 00/78001 



PCT/USOO/15690 



Whenever a Hostname changes, all URLs associated with all Devices addressed 
10 by that Hostname arc invalidated. The UDN is the only UPnP identifier guaranteed 

never to change. Any persistent associations maintained by applications should at least 
store the UDN to able to unambiguously identify the target Device. 
5 The lifetime of a Description URL is determined by Controlled Device or 

15 

Bridge that advertises it. If a Controlled Device or Bridge allows an SSDP ' 
advertisement of a Description URL to expire, the URL is invalidated. 

User Control Points use the Event Subscription URL returned by the Controlled 
2Q Device or Bridge to connect to the Event Subscription Server. This server does the 

10 housekeeping of remembering all User Control Points that are interested in receiving 

Events on a Service. The Event Subscription Server needs an address to send the events 
back to. This address is called the Event Sink URL, and is supplied to the Controlled 
^5 Device or Bridge in the GENA SUBSCRIBE message. The lifetime of an event 

subscription, and the Event Sink URL, is determined by the timeout on the 
15 SUBSCRIBE message. 

Ftuther details of UPnP addressing are listed in the following table. 

30 
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40 



45 
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15 



20 



25 



30 



35 



UFnP Addresses 



URL 



FancdoD 



Description URL Points to the Description Server and Document path on a Root 

Device. This URL is returned by the Description Server as part of 
the discovery process. 



Presentation URL 



Points to a Presentation (web) Server on a Controlled Device. 
There is one Presentation URL per Device, including Root Devices. 
This URL can be entered into the address bar of a web browser to 
navigate to the root web page of a Device. This URL is returned in 
the Description Document. 



Control URL 



Points to the Control Server implementing a Service on a 
Controlled De\ice. There is one Control URL per instance of a 
Service. This URL is returned in the Description Document. 

Event Points to an Event Subscription Server on a Controlled Device. 

Subscription URL This URL is returned in the Description Document. 



Event Sink URL 



Points to an Event Sink (an HTTP Server) on a User Control Point. 
This URL is specified by the User Control Point in the GENA 
SUBSCIBE message. 



40 



Device Discovery and Identification 

UPnP enables SSDP searches for a unique Root or non-Root Device by UDN. 
devices of a specified Device Type and devices containing a Service of a specified 
Service Type. 
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UPnP SSDP Level Searches and Results 



10 



15 



20 



25 



30 



35 



40 



10 



Search for 



Return* 



• -r { 



1 V r 

1': »•) 



J ■ t 



A unique Root 
Device (by L'DN) 

A unique non- 
Root Device (by 
IJDN) 



A single Description URL pointing to the Description Server and 
Document path on the Root Device. 

A single Description URL pointing to the Description Server and 
Document path on the Root Device that contains the non-Root 
Device. 



Type of Device 



Type of Service 



A set of Description URLs pointing to the Descnption 
Servers/Document paths of all Root Devices that match the Device 
Type, or contain a non-Root Device that matches the Device Type. 

A set of Description URLs pointing to the Description 
Servers/Document paths of all Root Devices that contain a 
matching Service, or contain a non-Root Device that contains a 
matching Service. 



SSDP specifies Service Type (ST), Nolificalion type (NT), and Unique Service 
Name (USN) header fields for queries and for annotincements. UPnP uses the ST or 
NT header to carry one of the UPnP defined identifiers. A unique USN is required for 
each unique SSDP announcement 

Multiple instances of the same Service Type within a Controlled Device 106- 
107 or Bridge 120 are not independently announced. 

UPnP search identifiers are used during the discovery process. The result of a 
successful discovery is one or more Description URLs. The format for search 
identifiers is: 



45 



15 



upnp:searchtype:[aUformat | UDNformat \ srvformat \ devformat J 
searchiype = [ UDN | SrvType | DevType | all ] 
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10 



15 



all/or mat = all 



UDNformat 
namespace 

sryformat 
devformat 



\SDK:namespace : uniqueid 
[ GUID I lEEEMAC | 1 394] 

Sw'Vy^,servicelype\ version 
DevType :devicetype 



20 



25 



30 



35 



40 



10 



15 



VPnP Search Idenii/Urs 



Formal; 



Example 



all 



upnp:al) 



upnp:all 



Unique Device Name upnp:UUN:namespace:uniq upnp:UDN: lEEEMAC :OC0099 
(UDN) ueid 123456 



Device Type 



upnp;DevType:cfe v/ce/v/w upnp:DevType : vcr 



Service Type 



wpnp'.SrvTypeiserviceiype.v upnp:SrvType:clock: I 
er 



SSDP specifies that SSDP announcements must be made for all SSDP 
searchable values. The SSDP announcements v^ith ^all" as the notification header value 
must carry the Root Device UDN as the USN header value. SSDP announcements for 
Device Types must carry the UDN of the Root Device concatenated with the Device 
Type URl as the USN header value. SSDP announcements for a Service Type will 
carr>' the UDN of the Root Device concatenated with the Service Type URI value as the 
USN header value. SSDP announcements of UDNs will repeat the UDN value as the 
USN header. 
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10 



UPnP SSDP Announcements 



15 



20 



25 



Announcement 


UPnF Notification 


SSDPUSN 


* 


■Type ^ ^ - f i 


■ : i ■■ > - V H r ' .•• - 
*- .1 , ' ■ . ' , . 




"all" 


Root Device UDN 


Unique Root Device 


Root Device UDN 


Root Device UDN 


Unique non-Root 


Non-Root Device 


Non-Root Device UDN 


Device 


UDN 




Device Type 


Device Type 


Root Device UDN + Device Type 




Identifier 


Identifier 


Service Type 


Service Type 


Root Device UDN + Service Type 




Identifier 


Identifier 
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35 



UPnP Bridges 120 (Figure 2) armounce Bridged Devices 122-123 and associated 
Services using SSDP. The identifiers associated with the Bridged Devices arc unique 
for the device, and they do not duplicate identifiers for Controlled Devices and Services 
directly available on the Bridge itself. This means that a Bridge that is also a Controlled 
Device must announce Bridged Devices and local Controlled Devices independently, 
with appropriate unique identifiers. Description Documents and associated URLs. 



40 



45 



10 Description 

The UPnP Description Document 226 (Figure 3) provides the information 

neccssar>' to identify, describe, connect and control a UPnP Controlled Device 106-107 

or Bridge 120 firom a User Control Point 104-105. 

The Description Document is an XML document UPnP defines the use of 

1 5 HTTP and XML for the Description Document and wire protocols. UPnP adheres to 
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20 



25 



the schema declaration rules of XML-Data and Y. Goland, **Flexible XML Processing 
10 Profile." 

The top level XML elements are separated into three categories: per Device, per 
Service and shared. 

15 5 Rehydiator 

With reference now to Figure 7, all (UPnP) Controlled Devices 106-107 (Figure 

1) or Bridges 120 (Figure 2) expose one or more Services 210-217 (Figure 3) that can 

be controlled remotely. Controlling such Services involves a message exchange 

between a User Control Point 104 and the device 106, This messai;e exchange happens 

10 according to a specific Service Control Protocol (SCP) 402. which specifies the content 

and sequence of the messages exchanged. 

User Control Points 1 04 are not required to have any prior knowledge of the 

SCPs 402 required to control the Services on the various devices. Therefore, a 

Controlled Device or Bridge must be able to describe to a User Control Point the 

15 protocols required to control its Services, such that the User Control Point will be able 

50 to implement these protocols dynamically. This requires a standard way of declaring 

Service Control Protocols in a concise and unambiguous fashion. UPnP introduces a 

technique for declaring Service Control Protocols using a series of XML documents. 

A Rehydrator 410 is a module that exposes a suitable API to applications and 

35 

20 either invokes Commands on a Service or queries the state of that Service, or receives 
and responds to events. The primary job of the Rehydrator is to map between API calls 
and the Service Control Protocol sequence that invokes the Command. 
40 As part of the Service Definition 406, a Service State Table 230 and Command 

Set 408 are defined. These things can be combined in a deterministic way defined by 

25 UPnP to produce a Ser\'icc Control Protocol Definition (SCPD) 406, which includes a 
Service Control Declaration 404 and a Service Control E>rotocol 402. The SCPD 406 is 

45 

a representation of the schema of a Service. It is possible to reconstruct the SST, 
Command Set and SCP from the SCPD. 
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The SCPD is directly embedded into the Description Document 226 of a 
Controlled Device. When the Description Document is uploaded into the User Control 
Point 104, the Rehydrator 410 can extract the SCPD from it. At this point, the 
Rehydrator has enough infonnation to issue Service specific SCPs 402. 

5 General Operation of the Rehydrator 

More generally with reference to Figure 8, the Rehydrator 4 1 0 operates as a 

universal adapter lo provide a programmalic interface to any service-specific protocol 

of a remote computing device. The Rehydrator 410 simply obtains a data description or 

declaration of the methods, properties and events of the remote service, as well as a 

1 0 dclinition of the protocol of network data messages through which the Rehydrator 

invokes the methods, queries or sets the properties, and receives event notifications. In 
UPnP, this data description takes the form of the Description Document 226, which 
contains a Contract 41 2. The Contract defines network data packets 413 (e.g., XML 
data), request/response patterns, and protocol (e.g., GENA, HTTP, SSDP) via which the 

15 packets are exchanged. This information is sufficient for the Rehydrator to exchange 
the appropriate networic data packets to interact with the Controlled Device Service, 
including to invoke commands, query and set properties, and receive and respond to 
events, without download of any executable code to the User Control Point 104 device 
and with a zero installation or configuration experience. 

20 The Description Document 226 also includes a declaration of the methods, 

properties and events for the Service. Based on this declaration, the Rehydrutor 
produces a corresponding programmatic interface for use by applications at the User 
Control Point The programmatic interface is an application programming inter&ce that 
can be in the form of an object integration interface of an object-oriented programming 

25 model, such as Microsoft COM, CORBA, Java classes, and scripting engine name 

extensions. In the example illustrated in Figure 8, the Rehydrator 410 exposes a COM 
object integration interface ("IClock" interface 41 4), with methods getTime() and 
setTimeO, for a Controlled Device having a "Clock" Service with GetTime and 
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15 



SetTime conunands. The Rchydrator 410 converts calls of an application program 416 
^0 to the IClock interface 414 into the network data messages specified in the Contract to 

invoke the corresponding commands of the Clock Service. The Rehydrator 410 
likewise creates suitable further programmatic interfaces for other Services (e.g., 
5 Services 210-217 of Figure 3) based on the Description E>ocumcnt of their respective 
Controlled Devices. 

Accordingly, the Rehydrator operates as a xuiiversal proxy object with data- 
driven conversion of programmatic interfaces to network data messages. Further, the 
20 Rehydrator produces the programmatic interface at the User Control Point based solely 

10 on an XML data description. This operation allows the Rehydrator to produce just-in- 
time transient interfaces to remote device Services without the complexity of code 
downloads and irLtnallation or configuration. Upon a later release of the interface by the 

25 

application, the Rchydrator destroys the interface without need to de-install or clean up 
persistent configuration data in a registry or configuration file of the operating system 
1 5 or object execution run-time. 

30 

Rehydrator Implementation 

Summary . With reference to Figure 9, a preferred implemenlation 440 of the 

Rehydrator 410 is as an internal Microsoft Windows component that routes service 

control requests from the UPnP API to devices. Applications wishing to control a 
35 , 

20 service on a UPnP device obtain a Service object through the UPnP API and tise the 

methods of this object to query the state variables of the service and invoke its actions. 

Those methods use the private Rehydrator API to turn the service control requests into 
40 network messages that travel lo the UPnP device. In this sense, the Rehydrator 

performs a mapping between API calls and network protocols. 
25 Basic Functionality . The preferred implementation of the Rehydrator is able to 

translate a service control call to the UPnP API into the appropriate network messages 

45 

defined by the Service Control Protocol. 
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Asynchronous Event Notification . The preferred implementation of the 
Rehydrator is able to notify UPnP API clients of any asynchronous events generated by 
the devices they are controlling. Event notification is done by means of the event 
interfaces defined below. 
5 Error Reporting . For a variety of reasons, state variable queries and action 

invocations may fail. The preferred implementation of the Rehydrator is able to provide 
a way to communicate the success or failure status of such operations to the parties 
initiating them. 

20 Rehydrator Implementation Design . As illustrated in Figure 9, the preferred 

10 implementation of the Rehydrator is used in two ways. First* the Device Finder 450 
uses it to create Service objects 460. Then, these Service objects use it to carr>' out 
service control operations (querying state variables and invoking actions). 

25 

Creating Service Objects . When the Device Finder 450 creates a Device object, 
it invokes the Rehydrator 41 0 to create Service objects 460 for each of the service 
1 5 instances on that device. Each service instance supports a partictilar Service Control 
Protocol and the Rehydrator needs a description of this protocol in order to create a 
properly hydrated Service object 

The Service Control Protocol is declared in two separate XML dociunents: the 
DCPD and the Contract. The Rehydrator needs the information in both documents. 
20 These two documents are passed to the Rehydrator as IXMLDOMDocument interface 
pointers in the RehydratorCreateServiceObJectQ API call. 

HRESUL'r 

40 RehydratorCreateServiceObject( 

25 IN IXMLDOMDocument ♦pDCPD, 

IN IXMLDOMDocument *pContractDocumcnt, 
OUT rUPnPScrvice **pNcwScrviceObject); 

45 This API returns a pointer to an fVPnPService interface on a newly created 

30 Service object In addition to the creating the Service object, the Rehydrator sets up its 



^ 39 



55 



wo 00/78001 



PCT/USOO/15690 



internal data structures so that it can properly handle requests to control the service. 
10 SpecLfically, it creates a list of the properties and actions exported by the service. Since 

all ser\'ice instances of the same service type export the same properties and the same 
actions, this information is kept only once for each service type and is indexed by 
5 Service Type Identifier. 

15 

The Rehydrator stores the information that is specific to a particular service 
instance as private data uithin the Service object itself. This includes the control URL 
and information about the control server 232 (such as the HTTP verbs it supports). The 
2Q Service Type Identifier is the link between the Service object that represents one 

1 0 instance of a service type and the Rehydrator internal data structures that contain 

information common to aJ] instances of that service type. The Service Type Identifier is 
stored as a private data member in the Service object. 

Querying Service Properties . Applications can query the values of service 
properties by invoking the IUPnPService::GetPropertyO method on a Service object. 
1 5 Internally, this method makes a call to the RehydratorQueryStateVariableQ function. 
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HRESULT 

RehydratorQueryStateVariabIe( 

IN LPCTSTR IpcszVcrb, 

20 IN LPCTSTR IpcszContiolURL, 

IN LPCTSTR IpcszSTL 

IN LPCTSTR IpcszVarName, 

OUT VARLANT *pValue); 



25 The first two in parameters to this function supply the service instance specific 

^0 information: the HTTP verb to use and the control URL to which the network messages 

will be targeted. The third parameter is the Service Type Identifier that will be used to 
locate the Service Control Protocol information in the Rehydrator*s internal data 
structures. The fourth parameter is the name of the variable that is being queried (the 

45 

30 Rehydrator will validate this against is internal list of state variables exported by the 



50 40 



55 



wo 00/78001 



PCT/USOO/15690 



service) and the final parameter is the address of a VARIANT sinictMrc in which the 
Rehydrator will place tlie variable's value. 

This function will generate an HTTP request to the control server on the device. 
The body of this request will be an XML fragment containing a XOAP-cncoded request 
5 for the variable's value. The following is an example of such a request (the exact 
header and payload format of this message is defined in the service contract): 



M-POST /clockService HTTP/1.1 

Host: spaiher-xeon:8586 
0 Content-Type: text/xml 

Man: "http://www, mi crosoft.com/protocols/cxt/XOAP"; ns=01 

01-MethodNamc: query State Variable 

01 -Message Type: Call 

Accept-Language; en-gb, eii;q=0.8 
5 Rcfcrcr: http://myhouse/VCRl Presentation 

Content-Length: 84 

User-Agent: MoziUa/4,0 (compatible; MSIE 5.01; Windows NT 5.0) 
Connection: Keep- Alive 

0 <qucryStateVaiiable> 

<variableName>currentTime</variableName> 
<;/querySiateVariabIe> 

The control server will respond to this message with another XML fragment: the 
5 XOAP-encoded method response. The following is an example of such a response: 

HTTP/1.1 200 OK 
Connection: Close 
Cache-Control: private 
0 Date: Mon Oct 1 1 12:13:38 PDT 1999 

Expires: Mon Oct 1 1 12:13:38 PDT 1999 
Content-Type: text/xml 
Content-Length: 62 

Man: "http://www.microsoft.com/protocols/ext/XOAP"; ns=01 
5 01-MessageType: CallResponse 

<queryStateVariableRespoiise> 
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<_retum> 12:13 :28</'_retum> 
<#'queryStateVariableRespon&e> 



The rehydrator will extract the return value from this XML fragment^ place it in 



5 the VARIANT structure whose address was passed as the last parameter to 
Re hydratorUetService Proper {yQ and then return. 

Invoking Service Actions . The process of invoking a service action is very 
similar to querying a state variable. An application calls IUPnPService::InvokeAction() 
on a Service object, passing it the name of an action to invoke, and an array of 
10 arguments to the action. Internally, lUPnPService:: Invoke ActinnQ calls 
RehydratorlnvokeServiceActionQy declared as shown below. 



As was the case for querying state variables, the service instance specific 
information is passed in the Urst Iwo parameters, followed by the Service Type 
Identifier in the third. The action name and an array of arguments are passed as the next 
25 two parameters, and the final parameter is the address of a variable in which to store the 
status of the operation. 

RekydratorlnvokeServiceActionQ will send an HTTP request to the control 
server identified by the second parameter. As before, the body of this qiessage will be 
an XML fragment containing a XOAP-encoded method call. An example HTTP 
30 reqtiest to invoke an action is shown below. 



HRESULT 



20 



15 



RchydratorlnvokeScrviceAction( 

IN LPCTSTR IpcszVcrb, 

IN LPCTSTR IpcszControlURL. 

IN LPCTSTR IpcszSTI. 

IN LPCTSTR IpcszActionName, 

IN SAFEARRAYsaActionArgs, 

OUT LONG ♦pStatus); 



M-POST /clockService HTTP/1 . 1 
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Host: spather-xcon:8586 
Content-Type: text^xml 

Man: *'hnp://www.n[iicrosoft.com/proiocols/ext/XOAP"; ns-01 
Ol-MethodName: invokeAction 
5 01-MessageType: Call 

Accept-Language; en-gb, en;q=0.8 
Referer: http://myhouseA^CRl Presentation 
^5 Content-Length: 1 1 9 

User-Agent: Mo2illa/4.0 (compatible; MSIE 5.01 ; Windows NT 5.0) 
Ifl Connection: Keep- Alive 

<Serialized S tre am main- ' ' invoke Action"> 
20 <invokeAction id="invokcAction''> 

<actionNamc>setCurrcntTimc<;'actionNamc> 
1 5 <aclionArg>l 5:4 1 :29</actionArg> 

<yinvokeAction> 
</Seri alizcdStream> 

25 

The encoding of the body of this meiisage is again specified in the service 

20 contract. The Rehydrator will wait for the HTTP response to this request, which would 

look something like the example below. 

HTTP/1 . 1 200 OK 
Connection: Close 
Cache-Control: private 
25 Date: Mon Oct 1 1 15:22:38 PDT 1999 

Expires: Mon Oct 1 1 15:22:38 PDT 1999 
Content-Type: text/xml 
^5 Content-Length: 50 

Man: "http://www.microsoft.com/protocols/cxt/XOAP"; ns=01 
30 01-MessageType: CailResponse 

<invoke ActionRc sponsc> 
40 <_retuin>0<y_rcttim> 

</invokeActionResponse> 
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After receiving a response such as this, the Rehydrator will extract the return 
value, place it in the out parameter it was passed, and then return. 

Figures 3 1 through 43 are program listings defining various interfaces used in 
the preferred implementation of the Rehydrator, including an lUPNPDevice Interface, 
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an lUPNPPropertyBag Interface, an lUPNPScrvtce Interface, an lUPNPDcviccs 
interface, and an lUPNPServices Interface. 

Description Document 

With reference to Figure 13, User Control Points 104 can retrieve a Description 
5 Document 226 hy issuing an HTTP GET on a Description URL. This URL is returned 
in the location header of either an SSDP announcement or an SSDP query response. 

The HTTP GET must include an accept-language header that is used to request 
the preferred language of the response. If the requested language is not supported, a 
Description Document in the default language supported by the Controlled Device or 
1 0 Bridge may be returned. 

An HTTP GET is used to retrieve sub elements of a Description Document that 
are expressed as URLs. 

URL Handling 

URLs embedded in Description Documents 226 take one of 3 forms: a fully 
1 5 qualified URL or a relative URL. 

Fully qualified URLs take the form: 
http://device name/pathname 

The devicename part of the URL is a Hostname or IP address and the pathname 

is a filesystem path or equivalent. A fully qualified URL is used ^as vs^ to establish an 

20 HTTP connection to a device. 

A relative URL does not contain the character and is of the form: 

pathname 
/pathname 

Relative URLS are a compact representation of the location of a resource 
25 relative to an absolute base URL. All relative URLs in a Description Document are 

appended to the value of the Description Document element <URLbase> to form fully 
qualified URLs. 
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Binary Data 
- 

iO Some elements of a Description Document are binary. XML docs not directly 

support the embedding of binary data. In order to include binary data directly in a 
Description Document^ one must convert the data to text using the Base 64 encoding 
5 scheme. This tends to increase the size of the data by 25*^0 on the average. Kiuch of 
this overhead can be eliminated if the binary data is passed by reference instead of by 
value. To reference binary data, a URL to the data is provided in a Description 
Document. The binary data can be retrieved by doing a HTTP GET with that URL. 
As an example, consider the <iniBgc> element in the following Description 
10 Document: 



25 



<iconLisP' 
<icon> 

<si2e>16</'size> 
1 5 <imagcType>PNG</imageType> 

<color> 1 <i'color> 
<depth>8</depth> 

<image> *Tittp://device.local/iconpath/icon.png"/> 
30 </icon> 

20 </iconList> 
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The icon would be retrieved with an HTTP GET of the following format: 

GET iconpath/icon.png HTTP 1.1 
25 Host: device, local 

The HTTP response would look like: 



HriP/l.l 200 OK 
30 Content- Type: image/png 

Content- length: ### 

<binflry color icon data in the PNG format> 



Description Document Layout 

The basic layout of the Description Document 226 is shown in Figure 14. 
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10 



15 



20 



25 



30 



35 



40 



The foilowing table lists Description Document elements that are sub-elements 
to the root elemenL 



Root 



The XML mot element of a IJPnP Description Document. 



spccVersionMaj The major version of the UPnP Architectural Reference that this 
or Description Document was created against. This value must be 1 . 

specVcrsionMaj The minor version of the UPnP Architectural Reference that this 
or Description Document was created against This value must be 0. 

URLBase An optional element used to construct fully qualified URLs. Relative 

URLS arc appended to the value of <iJRrBajie> to create fully qualified 
URLs. If this element is present, it must agree with the HTTP Base 
header. 

manufacturer A required element that contains a textual manufacturer name. 

manufactUXerU An optional element containing a URI . that points to the weh page of the 

manufacturer. 

RL 



modelName 



A required clement containing a tcxniai product name. 



45 



modelDescripti A required element containing a textual product description, 
on 

modelNumber An optional element containing a textual product model ntunber. 

modelURL An optional element containing a URL that points to the web page of 

the product 

UPC An optional element containing the product Universal Product Code 

(UPC). 

serialN umber An optional element containing a textual item serial nimiber. 
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The Description Document elements listed in the following table are associated 



with devices. 



rootDevice 



A required sub element of the root. This element is a container for one 
or more service elements and the elements that describe the rootDevice. 



device 



An optional sub element of the root or another device element. This 
element contains the same kinds of elements as a rootDevice element. 



UDN 



A required sub element of every rootDevice or device element 
containing the Unique Device Name. 



fiiendlyName A required sub element of every rootDevice or device clement 

containing a textual friendly name. This element can be updated 
remotely. 

deviceType 



A required sub element of every rootDevice or device clement 
containing a standardized Device Type Identifier. 



presentationU An optional sub element of a rootDevice or device element containing a 
RL Presentation URL. 



iconList 



A required sub element of every rootDevice or device element. This 
element is a container for one or more icon elements. UPnP requires a 
base set of six icons that must exist in the iconList All devices must 
support PKG icon image forafiats of three sizes, 16 by 16, 32 by 32 and 
48 by 48 pixels in both color and black and white at 8 bit depth. 
Additional formats and sizes, including JPEG, GIF, BMP, ICON and 
VML, may be supported by adding them to the list. 



icon A required sub element of every iconList clement. This clement is a 

container for the elements that define an icon. 

size A required sub element of every icon elemenL There must be icon 
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elements with associated size elements with the values 16, 32 and 48. 
Other icons may specify other sizes. 



color A required sub element of every icon element with value 0 or 1 . Each 

icon of size 16, 32 ur 48 must exist in color and black and white. 



depth 



A required sub element of every icon element. All required icons must 
exist with a value of 8. 



imageType 



A required sub element of every icon element that identifies the format 
of the binary icon: png, jpcg, vml, gif, brap, or ico. 



image A required sub element of every icon element that references a binary 

icon. 

The following elements of the Description Document are associated with 
Services. 



service An optional sub element of the rootDcvice or another device element. This 

element is a container for the Service Definition. 

serviccType A required sub element of every service element containing a standardized 
Service Type Identifier. 



controlURL A required sub element of every service containing a Control URf,. 



eventSubUR A required sub clement of every service containing an Event Subscription 
L URL. 



SCPD 



A required sub element of every service. The SCPD is a container for the 
standardized Service Control Protocol Declaration associated the Service. 
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Figtire 1 5 shows an exemplary icon list in a Description Document 226. 
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Service Control Protocol and SCP Declaration 
10 As part of the Service Definition 406 shown in Figure 7, a Service State Table 

230 and Command Set 408 are defined. The SCPD 406 is a representation of the 
schema of a Service. It is possible to reconstruct the SST 230, Command Set 408 and 
5 SCP 402 &om the SCPD. 

15 

The declaration of such a protocol must ^cify the list of Variables that can be 
queried, the set of Commands that can be invoked, as well as the wire protocol (the 
content and sequence of networic messages) required to carry out these operations. 
2Q SCPD is specified in two XML documents. The first or Service Control Dcfimtion 

10 document 404, witten in a language called Service Control Protocol Declaration 

Language (SCPDL), declares the list of state Variables and Commands associated with 
the Service Type to be controlled by the protocol. The second or Service Control 
Protocol document 402 is written in Contract Definition Language (CDL) and declares 
the wire protocol that will be used to query the values of the state variables and invoke 

1 S the actions associated with the service. 

Declaring the Service State Table and Command Set 

A SCPDL document 404 is used to specify the list of state Variables that a SCP 
can query and the set of Commands that it can invoke. SCPDL is an XML schema, a 
set of rules for writing XML documents (Service Control Protocol Declarations). 

35 

20 Figure 16 shows an exemplary SCPDL document. This XML docimient 

consists of a root <scpd> element containing two sub-elements, <serviceStateTable> 
and <actionLixt> . Within the <serviceStateTable> element is a <sta(eVariable> 
40 element for each state variable associated with the service. The Service in this example 

is a TV timer with has only one state variable, currentChanneL The elements within the 

25 <stateyariable> element specify the name, data type and allowed values for the state 
variable. Had the Service more state variables, they would be represented by additional 
<stateVariable> elements within the <deviceStateTabie> clement. 
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The <actionLisi> element contains an <action> element for every action 
associated with the Service. The elements within an <aaion> element specify tlic 
name of the action and any arguments the action may take. In this case, the service 
supports two actions that do not take arguments, ChannelUp and ChannelDown, and 
5 another, SeiChannel^ tliat takes a new channel number as an argument. The 

<argumeni> element and the elements nested within it define the argument The 
<relateciStateVariable> element within <argument> specifies the name of one of the 
state variables to which the argtmient is related. In the UPnP Device Model* all 
arguments to actions must correspond directly to some state variable. 

10 Declaring the Contract 

The Contract is a specification of the wire protocol that will be used to query 

state Variables* invoke Commands and carry notifications or events. This contract 

specifies the type of protocol used, the network endpoint to which messages are sent, 

the contents of those messages, the contents of the expected responses and the contents 

15 of events. Contracts are written in Contract Definition Language (CDL). 

All UPnP SCPs will use essentially the same contract- A specific contract 
applies to a single Service instance (since it specifies the network endpoint to which 
messages are sent and network endpoints are specific to service instances). However, 
other than the networic endpoint definition, all contracts for all Service instances should 

20 be the same. 

Figures 17-19 show an exemplary Contract. This Contract defmes two methods: 
queryStateVariahle and invnkeActinn. These methods are invoked by exchanging XML 
mcssages with a Control Server on a UPnP Controlled Device or Bridge, llie Contract 
completely defines the header and payload of each message. By passing the appropriate 
25 arguments to these methods, any of the state Variables declared in the SCPDL 
declaration can be queried and any of the actions invoked. 

Figures 20 and 21 show an XML schema for the SCPDL. 
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Basic UPnP Eventing Architecture 

With reference to Figure 22, the UPnP architecture 200 (Figure 3) requires that 
clients of the UPnP API be enabled to receive notifications reliably from UPnP services 
2 1 0-217 as their states change. Since state changes are relatively common, the eventing 
5 subsystem is efficiency and performance is a major consideration in this design. Fij^ure 
22 and the following discussion describe the Basic UPnP Eventing Architecture 600, 
which encompasses both the controlled device (CD) 106 and user control point (UCP) 
104 sides of the eventing service. It also includes the support APIs for both a low-level 
20 service interaction and a higher level COM-based wrapper of those APIs. The latter 

10 enables automation controllers like Visual Basic and JScript 602 to receive event 
notifications. 

25 What is an event? 

Property change events are defined as any change in the value of a row of the 

Device State Table (DST) 230 (Figure 3) for a service 210-217. This change will be 

1 5 reflected as a property change notification. For example, if a "VCR" device has a 

"VCR Transport" service, one row in that service's DST may be TapeState and the 

value could be TapePresent. If the tape is ejected, the new value would be TapeAbseni. 

This state change would be reflected as a notification sent to all subscribers. 

What is a notification? 

20 A UPnP event notification is an XML message sent over HTTP/TCP to each and 

every subscriber to a particular UPnP service. The content of the XML is defined 
below. The important contents of this message are the unique identifier for the 
subscription, the property name, new value, and property type. 

Notification Processing 
25 In UPnP. the listener to Notifications is the SSDP service itself. SSDP ab^ady 

listms on another multicast address for "alive" and "byebye" messages sent by UPnP 

devices. The same listener will listen on a TCP port for notifications sent. All 
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subscriptions sent from that UCP contain the same callback URL and so all 
notifications will be directed to that URL. When a notification arrives the SSDP service 
will exaraine the NT header of the message and determine if it is an event notification. 
If so, the message is parsed further to determine if it should be forwarded on to 
5 subscribers (which must exist). GENA defines the fonnat of the HTTP message, what 
headers can be used, and what they can be used for. 

GENA 

GENA is the protocol of communication that, in a preferred embodiment, UPnP 
devices use to send event notifications. Therefore, UPnP devices that wish to notify 
0 UCPs of state changes are recommended to use GENA. Notification subscribers will 
never be required to interact with a UPnP device directly and so they are not required to 
use GENA. TThe eventing API wiU encapsulate this complexity. Other appropriate 
event transport protocols may be used, such as publish/subscribe systecns. 

Receiving Notifications 
5 Applications written in C (C Application 604) will be able to utilize the SSDP C 

API 61 0 to receive callbacks when notifications are processed by the SSDP service. 

This is analogous to SSDP clients registering for notifications that services have 

become available. When a UCP registers for a notification, it passes as a parameter the 

URL of the service for which it is interested in receiving notifications. This URL is 

^0 obtained from the description document for thai service. (When a service is registered 
on a UPnP device, it uses this same \SRh to listen for .subscription requests). 

When a notification message is received by the SSDP service listener, the SID 
header is checked against the list of subscribers it maintains. If a subscriber is found, 
the callback fijnction for that subscriber is invoked, with one of the parameters being 

[5 the contents of the notification message. The notification client that implements the 
callback function can process this message in any appropriate way. 
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Notifications in the UPnP API 
10 The UPnP API 4 10 is a consumer of the basic C interface provided by the SSDP 

C API 610 component. In order to integrate seamlessly, the registration of notifications 

is handled by the Service Object 61 2 inside the UPnP Object Model. Service objects 

5 will register for notifications when they are created. This ensures that the DST is 

15 

maintained by the UPnP API and is kepi up to date. They will implement the callback 
function required by the registration function. If this callback function is invoked, it 
will pass on that notification to UCPs. The UCPs can be written in C, C-H-, VB, or 
2^ script code, so the mechanism for passing on notifications can be different 

10 Script Support 

A feature of the illustrated eventing system is that it supports script languages 

such as VBScript and JavaScript 602. For VBScript, this is made possible by providing 

25 

a property on the Service object that, when set, contains the IDispatch pointer for a 
VBScript function or subroutine that will be the event handler. When the Ser\Mce 
15 object^s notification callback is invoked, it checks to see if this IDispatch pointer was 
30 set, and if so, it calls IDispatch: rlnvoke on DISPID 0 of that interface to call the 

VBScript subroutine. An equivalent mechanism is implemented for JScript. 

Eventing Subsystem Terminology 

UCP — User control point Any piece of software that searches for devices and 
20 controls them. 

Cn — controlled device. A hardware or software device that announces its 
availability thru SSDP and allows control by UCPs. 
^ Subscriber - A UCP who wishes to be notified of event changes. 

Notifying Resource (or simply "Resource") - For the purposes of this 
25 document, this will always be a service contained within a UPnP CD 106. 

Event Source - a service that provides events. UPnP services are event 

45 

sources. AH notifying resources are event sources and vice versa. 

Event - message generated when a change in a resource's state occurs. 
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Property - a single entry in the service's state table whose Default Value can 
change. Properties and events always have a one to one correspondence. 



Subscribing To Resoiirces 



5 



hitegratlng With The UPnP API 

The UPnP API 410 exposes several interfaces with which a consumer can find 



and enumerate devices, control services, and get properties on devices and services. To 
allow the integration of events into this model, we add a new property to the 
lUPnPService interface called EventHandler. When this property is set. it tells the 
Service object 612 that its client is interested in receiving notifications for that service. 

10 The SSDP API RegisterNotificationO API is called when the Service object is created 
so that it can maintain a local copy of the DST for that service. The Service object 
knows the URL of the service and therefore it can provide this as a parameter to 
RegisterNotificationO. RegisterNotificationO is also provided a callback function 
which is a static member of the Service object class. This function will be invoked for 

1 5 each and every notification sent by that particular UPnP service. 

The Notification Callback 

The Ser\'ice object 612 includes a static member funaion called 
EventNotiJyCallbackO which is invoked for each notification sent by the UPnP service. 
The callback is passed the entire HTTP message contents in a slruclure which is a 
20 parameter to the function. The prototype looks like this: 



The ssdpType parameter should always be SSDP_PROPCHANGE. The 
pssdpMsg parameter contains the relevant information about the event The key piece 



25 



static VOID 

CUPnPService::EventNotifyCallback(SSDP_CALLBACK_TYPE 
ssdpTypCj 

SSDP_MESSAGE "pssdpMsg, 



LPVOID pcontext); 
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of information is the body of the XML message. The body contains information about 
10 wliat property changed, what its new value is and what type it is, among other 

information. The pConiext parameter will always be the this pointer of the Service 
object. This allows the code to call a method to fire the event to the UCP. The callback 
5 will parse the XML body using the XML DOM services. Property changes are iterated 
and the local DST is updated to reflect these changes. After this processing is done, an 
event notification may be fired for each property that was changed to the owner of the 
subscription if one exists. Depending on what environment the owner is witten in 
2Q (C-H- or script, etc. . .)» a different mechanism for firing the event may be employed. 

1 0 A special case for this process is the very first notification received after a 

subscription is established. This notification contains the entire set of properties and 
their values and is used to locally sync up the DST. Events will not be fired to clients 
25 of the UPnP API in this case. 

Firing Notifications 

15 When the EventNotifyCallbackQ function is called, the local copy of the DST 

30 for the service is updated. After this, an event needs to be fired if a subscriber exists. A 

subscriber exists if the put_EventHandlerO method was called, either from VBScript, 
C++ code, or another source. To abstract away this complexity, a new interface called 
lUPnPF. vents is needed. 

35 

20 This interface currently has one method called NotifyEventO which takes 

several parameters (TBS). When put_EventHandlerO function is called, its argument 
is an lUnknown. This pointer is Qucrylnterface'dQ for IDispatch first, and if it 
succeeds, then IDispatch: :InvokeO is called with DISPID 0 to invoke the de£ault 
method. This allows VBScript 602 to be called. If that fails, however, it is Queried for 

25 lUPnPEvents, and if that succeeds, the NotifyEventQ method is called with the same 
parameters as for InvokeQ- The handles C++ UCPs effectively. 

45 
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Subscribing with C-H- 

To subscribe to a UPnP service from C++, a UCP tiistantiatcs a UPnP service 
object, issues Query InterfaceQ to it for lUPnPEvenis, and calls the 
IUPnPEvents::SetEventCallbackO function. This function takes 2 parameters, a 
5 callback function pointer and a context pointer. 

Subscribing With VBScript 

To subscribe to a UPnP service's events, all that needs to be done by a script 
602 is to create a function or subroutine as a handler function and set the pointer of that 
function lo the EventHandhr properly of the Service object. Now, anytime an event is 
0 fired, this VBScript function or subroutine will be called. In VBScript, this is written as 
the following: 

Dim UPnP API 

Set UPnP API - CreateObjectC*UPnPAPI.r*) 

5 

Devices = UPnPAPI.FindDevices(...) 
For each device in Devices 

For each service In deviccs.serviccs 
If service.dcpi - "cloclcvl" 
,0 Service.EventHandler = 

GctRcfi["clock_PropertyChangedT 
End If 
Next service 
Next device 

;5 

Sub clock_PTX3pertyChangcd(prop, value) 

MsgBox "The time has changed. It is now ** & value & 
End Sub 

0 In this example, the script enumerates all devices, looking for any device that 

supports the *'Clock" interface. When it finds a device that supports that interface, it 
enumerates that device *s services looking for the one that has the "clock-vl** interface. 
Once it finds that service, it sets that service's EventHandler projjerty to the VBScript 
subroutine called •*clock_PropertyChangcd'*. This name is arbitrary. 
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Sending and Receiving Notifications 
GENA Client API 

GENA cJients are actually UPnP services. A GENA client creates a new event 
source when it is initialized. The GENA client API 620 facilitates this. It also provides 
5 a way for GENA clients to send their notification messages. It is also important to note 
that the HTTP server that lives on the UPnP device is also a client of this API. The 
GENA client API consists of the following functions: 

ReKisterUpnpEventSourceQ 

The RegisterUpnpEventSource() API gives a GENA client the abilit>' to register 

1 0 itself as an event source. The prototype is as follows: 

BOOL RegisteKJpnpEventSource( 
LPTSTR szRe<iuestUri. 
DWORD cProps, 
UPNP PROPERTY ♦rgProps 
15 ); ~ 

Parameters: szRequestVri fin] an arbitrary Request-Uri that SUBSCRIBE 

requests will be sent to. When a SUBSCRIBE request arrives at the given URI, it is 

acknowledged and the subscriber is added to the list of notification recipients. Note that 

this URJ should match the URI provided in the description for this service. CProps [in] 

20 the number of properties that this event source provides. RgProps [in] Array of 

UPNP_PROPERTY structures which contain information about each property. ITic 
property information is derived from the DST for the event source. 

Return Value: The function returns a TRUE if successful. If the given URL has 
already been registered as an event source, the return value is FALSE and 

25 GetLastError<) returns ERROR_ALREADY_EXISTS. 

Notes: The initial state of the event source needs to be given to the API so that it 
can effectively maintain the up-to-date state of the event source. 
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DeRegisterUpnpEventSourceQ 
iO The DeRegisterUpnpEventSourceO API gives a GHNA client the ability to 

deregister itself as an event source. The prototype is as follows: 

VOID DcRcsistcrUpnpEventSource( 
5 LPCTSTR szRcquestUri 

); 



15 



20 



Parameters: szRequestUri [in] an arbitrary Request-Uri that SUBSCRIBE 
requests will be sent to. When a SUBSCRIBE request arrives at the given URI, it is 
10 acknowledged and the subscriber is added to the list of notification recipients. Note that 
this URI shotild match the URI provided in the description for this service. 

UPNP PROPERTY 

typcdcf struct _UPNP_PROPERTY { 
LPTSTR szNamc; 

" 15 LPTSTR szVaJue; 

LPTSTR szType; 
} UPNP_PROPERTY; 

Where szName is the name of the property, szValue is the current value of 

30 

20 property, and szType is the type of property (string, integer, etc. ..)• 
SubmitUpnpPropcrtyEventQ 

The SubmitUpnpPropertyEventO API allows the GENA client to submit a IJPnP 
property change event to be sent to subscribers as a notification. The protot>'pe is as 
follows; 

25 BOOL SiibmitUpnpPropertyEvent( 

LPCTSTR szRcqu«tUri. 
DWORD dwFlags. 
^ DWORD cProps, 

UPNP PROPERTY *rBProps 

30 ); 



45 



Parameters: '^"szRequestUri [in]" identifies the event source to which this event 
belongs. This is the same Request-Uri passed to RegisterUpnp£vcntSource(). 
**DwFlags [in]" is unused. **CProps [in]" is the number of events that are being 
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submitted. "^KgProps [in]" is an array of UPNP_PROPERTY structures which contain 
^0 information about each event. 

Return Value: If the function fails, the return value is FALSE. The get extended 
error information, call the CetlastErrorQ function. 
5 Notes: When a series of properties is submitted for event notification^ the local 

version of the property state for the given event source is updated wih the list of 
properties passed in. SubmitUpnpPropcrtyEvcntO calls SubmitHventQ after it has 
generated an XML body. 
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SubmitEventQ 

1 0 The SubmitEventO API allows the GEN A client to submit an unstructured event 

to be sent to subscribers as a notification. The prototype is as follows: 



BCX)L SubmitEvent( 
25 LPCTSTR szRequestUri, 



DWORD dwFlags, 
15 LPCTSTR szHcadcrs, 

LPCrSTR szGvcntBody 

); 

Parameters: SzRequestUri [in] identifies the event source to which this event 



belongs. This is the same Request-Uri passed to RegisterUpnpEventSource(). DwFlags 
20 [in] Unused. SzHeaders [in] null-terminated text string containing the headers for the 
event, each separated by CRLF. SzEventBody [in] null-tenninated text string 
35 containing the body of the event message 

Return Value: If the function fails, the return value is FALSE. The get 
extended error information, call the GetLastErrorQ function. 
25 Notes: If no subscribers exist, the function does nothing. If one or more 

^ subscribers exist, a message is sent to each subscriber. SubmitEventO will always .send 

to all subscribers. 

UPnP Controlled Device Architecture 

In UPnP, every UPnP service 210-2 1 1 that supports property change event 
30 notitl cations is to be a GENA client. Therefore, when the service is initialized, it must 
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register itself as a GEN A event source. It will do this with the 
RegistcrUpnpEvcntSourceO API- This returns a handle which can be used in 
subsequent APIs. 

RegistcrUpnpEvcntSourceO takes a URL and an array of properties as 
5 parameters. Inside the API, an entry in an array of structures is initialized and the index 
is returned as the handle. The structure contains the source URL as one of the 
members. A second member of the structure, an array of destination URLs, is left 
uninitialized. This is filled in each time as subscriber is added for thai event source. 
Another member of the structure is the list of properties that this event source provides. 
10 This is effectively a cached copy of the DST for the event source. As events are 
submitted, the local properties are updated. 

When SubmitUpnpPropertyEvent() is called, each propoty submitted replaces 
the corresponding property already maintained by the API. If no subscribers exist, the 
request to submit an event is ignored. If one or more subscribers exist, their callback 
1 5 URLs are looked up in the list of subscribers for the given event source and a NOTIFY 
message is constructed and sent to each URL, one at a time, in order of subscription. 

If an event is submitted and no response is received (or a CD-side error occurs), 
the CD continues to attempt to send to the UCP. If the subscription timeout expires, 
then the subscription is removed. If the UCP becomes available again, it will re- 
20 subscribe because it wiU notice the sequence nimibers are not contiguous. 

When an HTTP server 626 receives a SUBSCRIBE message, it passes it along 
to a function which parses the message for the necessary information. The Request- 
URl identifies the service that is to be subscribed to. The callback URL is obtained 
from the "Callback" header. Since the Callback header can contain multiple URLs, it 
25 picks the first "http://*' URL it finds. It then adds the subscriber to the list of subscribers 
for this event source. A unique subscription identifier is constructed which it will send 
back to the subscriber in the HTTP response to the SUBSCRIBE request 
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If no event source matches the Request-URI firom the subscription message, the 
10 I ITTP server should return "404 Not Found". 

When a subscription is added, the local copy of the DST is sent as a NOTIFY 
message. This special NOTIFY message contains sequence number 0 which informs 
5 the UCP that this is an initial state population event and not a notification where every 
event has changed. 

When a CD receives an UNSUBSCRIBE message, it checks the "SID" header 
to obtain the subscription identifier. It looks up the subscriber ID in the list of 
20 subscribers for that event source and removes the destination URL entry associated witli 

10 it 

GFNA Server API 

25 GEN A servers 630 arc generally going to be UPnP UCPs. A GENA server is 

anything that receives and processes NOTIFY messages to handle notifications from 
resources and sends SUBSCRIBE and UNSUBSCRIBE messages to receive 
1 5 notifications from resources. These APIs leverage the already existing SSDP APIs. 
The following are the changes to the APIs: 
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RegisterNotificationQ 

The RegisterNotificationO allows a UPnP UCP to request notification when an 
event occurs for a given UPnP service. The prototype is as follows: 

20 HANDLE RcgistcrNotification( 

NOTIFY__TYPE nt, // SSDP_ALIVE | SSDP PROPCHANGE 

I r? 

LPTSTR szRcsourceType, // based on NOTIFY TYPE» unused if 

4Q // SSDP_ PROPCHANGE is used. 

25 LPTSTR szEvcntUrU 

ServiceCallbackFunc fbCallback, 
void 'pContcxt 

); 
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Parameters: Nt [in] An enumeration that determines the type of notification 
reqxiested. The values are: SSDP_ALIVE - a service has become available, and 
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SSDP_PROPCHANGE - a property has changed on the service, SzResourceType [in] 
A auU-tenninated string specifying the resource type desired. For SSDP_ALIVE» this 
is the service type, for SSDP_PROPCHANGE this is unused. SzEventUrl [in] A null- 
terminated string specifying the URL that a subscription request should be sent to. 
5 FnCallback [in] A pointer to a ftmction that wi(l be calied each time a notification is 
received. The function pointer is defined in the SSDP spec. PContext [in] This 
parameter is included as a parameter when invoking the client-supplied callback 
function. 



10 subsequent call to the DeregisterEventNotificationQ function. If the function fails, the 
return value is INVALID_HANDLE_VALUE error code. To get extended error 
information, call GctLastError. 



UPnP UCP Architecture 

When a UPnP UCP wishes to subscribe to notifications for a particular UPnP 
service, it calls the RegisterNoiification() API. It passes to this API a notification type 
25 that identifies the type of notification being requested, a URL to which a subscription 
should be sent, and a callback function and context for use v/hen the notification is 
received. 

RcgisterNotificationQ will compose a SUBSCRIBE message, using the data 
passed in, and send that to the URL specified by the caller. The Callback header of the 
30 SUBSCRIBE message will be composed on the fly, as an arbitrar>' URL for 

notifications to be sent to for this subscription. This callback URL will likely be a 



Return Value: If the function succeeds, the return value is a handle used in a 



ServiceCallhackFunc 



20 



15 



typcdef cnum SSDP_CALLBACK_TYPE { 
SSDP_FOUND-0, 
SSDP ALIVE - 1, 

ssdpIbyebye=2, 
ssdp_donr-3. 
ssdp_propchange = 4. 
) ssdp_callback_type,* pssdp_cal.lback_typn; 
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constant since the server .API wilJ always know how to handle requests sent to this 
URL. It will then send the SUBSCRIBE message and await a response. 

RegisterNotificationO in the SSDP API does not currently send HTTP requests, 
but it can be modified to do so. It also needs to await a response which it will also be 
5 modified to do so. 

When the response is received, the Subscription-ID header contains a SID which 
is associated N^ith the callback function specified by the caller. 

Immediately after the response is received, the UCP should expect an initial 
NOTIFY message that contains the complete set of properties maintained by the CD. 

10 This becomes the local cached DST on the UCP side. From this point on. all 

modifications to the table are made via NOTIFY messages. This initial NOTIFY 
message will have sequence number 0 that indicates it is an initial property set and not 
an update. The UCP can use this inforaaation in any way it sees fit. This enstires the 
UCP's state table is always in sync with the one on the CD. 

15 When a message is ceceived by the HTTP server on the UPnP UCP, it is passed 

to a function which determines the method name and Request-URI. If this is a NOTIFY 
message, the headers are parsed and packaged up into a structure. The callback 
function that was specified to RegisterNotificationO is called with that structure as one 
of the parameters. UCPs who implement the callback function can find the headers and 

20 body of the NOTIFY message and do additional processing based on the notification 
type. 

This all requires that the SSDP HTTP server listen on a TCP socket in addition 
to the UOP multicast port it already listens to.' However, once a NOTIFY message is 
received, it is processed in the same way regardless of from which connection it 
25 originated. 

Handling Failures 

The following are subscrtption/notiflcatioa failures that can occur and their 
soltitions: 
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Leaked Subscriptions 

10 To protect against subscriptions that exist on the controlled device, but no longer 

on the UCP, we institute the timeout feature of GEN A subscriptions. The scenario is 
this; A UCP subscribes to a CD. then the UCP reboots. Meanwhile, the CD is still 
5 trying to send notifications to that UCP. If the UCP never comes back, the subscription 
would be leaked because the UCP never told the CD that it was going away. So to 
correct this, each subscription request includes an arbitrary timeout value which 
indicates to the CD that the UCP will be re-subscribing every n seconds indicated in the 
20 timeout header of the subscription request. If the timeout expires on the CD, the 

10 subscription is removed. The UCP is required to re-subscribe before the limeout period 
has elapsed. If it fails to do so, the subscription will be terminated by the CD. 

Some time before the timeout expires on the UCP, a re-subscribe message 
should be sent. The re-subscribe message is similar lo the subscribe message, but it 
does not contain an NT or Callback header. If the UCP is imable to re-subscribe within 
1 5 the timeout period, the subscription will be terminated by the CD. If the UCP sends a 
re-soibscribe after the CD has terminated the subscription, the CD will return "412 
Precondition Failed". 

Reboot of a Controlled Device 

If a controlled device reboots, information about all of its subscribers would be 

35 

20 lost. To prevent this, the subscriber information will be persisted across reboots of the 
device. Because the subscription info contains a timeout member, the absolute 
expiration time will be used when the subscription information is persisted. That way, 
4Q when the device comes back up, it can check the timeout for each subscriber and if that 

time has passed, the subscription will be removed. 



45 



50 



25 Networic Error Sending Event Notifications 

If a controlled device receives an error sending an event notification lo a 

subscriber, it will NOT cease to send notifications. It will continue to send notificatiorjs 

and receive errors until the subscription expires. The problem for the UCP is that it will 
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have missed a number of event notifications and so its state table will be out of sync, 
^0 To correct this, each event notification message will contain a 32-bit sequence number 

that starts at 0 and increments for each message sent to a subscriber. If a subscriber 
receives a notification with a sequence number that is not exactly one more than the 
5 previous notttication, it will know that it has lost events and will ignore all future 

notifications until it receives one with sequence number 0 again. Events with sequence 
number 0 indicate that the event is an "initial state" event. 

Once it realizes that is has lost one or more events, the UCP will send an 
20 UNSUBSCRIBE message, followed by a SUBSCRIBE message. This is not die same 

10 as a rc -subscript ion because re -subscriptions do not cause the CO to start the sequence 
over at 0. In this case, the active unsubscribe/subscribe will cause the CD to restart the 
sequence at 0 and send the entire state table with the first notification message. 

25 

The SUBSCRIBE Message 

When a UPnP UCP ^^'ishes to subscribe to event notifications for a UPnP service 

15 2 1 0-2 1 1 , it will form a SUBSCRIBE message of the following format: 

30 SUBSCRIBE servicel HTTP/I.l 

Host: vcr. local :200 
NT: upnpcevent 

Callback: <http://danielwe/upnp:923> 
20 Timeout: Second-600 



35 



40 



The response is as follows:: 
HTTP/1.1 200O.K. 

SID: uuid:kj9d4fae-7dec-l Id0-a765-00a0c91e6bf6 
25 Timeout; Second-600 



This example of a GHNA SUBSCRIBE request and response demonstrates a 
subscription to event notifications for "servicel.*' The host is "vcr.local." All 
notifications for this service will be sent to the callback URL http://danielwe/upnp:923. 
30 In the response, the *'Subscription-ID" header provides the subscriber with an identifier 
to use when it wants to unsubscribe to this resource. The "Timeout** header indicates 
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that the subscriber will send a rc-subscription request before 10 minutes have elapsed. 
^0 If tlie device does not receive this request within that period of time, it will remove the 

subscription. 

The Re-SUBSCRIBE Message 
15 5 When a UPnP UCP wishes to re-subscribe to event notifications for a UPnP 

service, it will form a SUBSCRIBE message of the following format: 

SUBSCRIBE servicel HTTP/1.1 
Host: vcr.local:200 

SID: uuid:kj9d4fae-7dec-l Id0-a765-00a0c91e6bf5 
10 Timeout: Sccond-600 

The response would be as follows:: 
HTTP/l.l 200 O.K. 

SID: uuid:kj9d4fae-7dec-l Id0-a765-00a0c9le6bf6 
15 Timeout: Second-600 

Note that the NT and Callback headers are absent, but the SID header exists. 
This tells the CD 106 which subscription is being renewed and restarts the timeout. 
30 When the CD receives this message, it will persist the subscriptions to disk (or other 

20 persistent data storage medium), updating the absolute timeout based on the current 
time and a new timeout sent by the UCP (if it was different). 

35 The NOTIFY Message 

When a resource wishes to send an event notification, it will form a NOTIFY 

message of the following format: 

25 

40 NOTIFY upnp HTTP/1 . 1 

Host: daniclwc:923 
NT: upnp: event 
NTS: upnp:propertyclianged 
30 SID: uuid:kj9d4fae-7dec-l Id0-a765-00a0c91e6bf6 

Seq: 123 

^ Content-Length: xxx 

Content-Type: text/xml 
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<event XML schema> 

The response is as follows:: 
HTTP/1.1 200 O.K, 

5 

This example of a GENA NOTIFY request and response demonstrates that a 
"upnp:propcrtychanged" event is being sent to http;//danielwe/upnp:923, I'he USN 
header identifies "vcr. service I" as the event source. The XML contains the property 
name, value, and type. The *'Seq" header indicates the sequence number of the 
10 notification. Sequence number 0 indicates the initial state update for the subscriber. 

Property- Change bvent XML Schema 

A UPnP property change event will be of the following form: 

<U:propertyset xmljii>:U=''upnp'^ 
1 5 <U :propcount>2<AJ :propcount> 

<U:property> 
<U:foo> 

<U :type>string</U :type> 

goodbye 
20 </U:foo> 

<^:propcrty> 

<U:propcrty> 

<U:bar> 

<U:type>integer<AJ:type> 
25 27 
<.aj:bar> 
</U:propcrty> 
</U :propcrtyset> 

30 Here, a property named "foo" is of type "string** and has a value of "goodbye" 

and a property named "bar" has a type of "integer" and has a value of 27, The XML 
will be contains a list of multiple properties that have changed, along with a coimt to 
make it easy to determine this. 
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The UNSUBSCRIBE Message 

When a UPnP UCP wishes to unsubscribe to event notifications for a UPnP 

service, it will form an UNSUBSCRIBE messat^c of the following format: 

UNSUBSCRIBE service 1 HTTP/l.l 
Host: vcT.local:200 

SID: uuid:kj9d4fae-7dec-l Id0-a765-00a0c91e6bf6 

The response would be as follows:; 
HTTP/l.l 200 0.k. 



10 

20 



This example of a GENA UNSUBSCRIBE request and response demonstrates 
that the UCP is no longer interested in receiving event notifications from 
http://vcr. local/service 1 :200. 

Step By Step: UCP to CD & Back 
1 5 This section will take a step by step approach to what happens on both sides 

(UCP & CD) of an event notification. The description starts at the initialization of a 

UPnP device. Figure 23 illustrates the subscription, notification, and unsubscription 

30 process. 

20 1. A UPnP device called "vcr" initializes. 

a. It sets itself up to be an HTTP server by doing the following: 

35 

i. It binds to a TCP socket using its IP address and an arbitrary port 

number. This addrcs&'port pair will be referenced by all incoming URL 
requests. 

^ 25 ii. It listens for incoming connection requests on that socket and sets itself 

up to accept any incoming connections. 

b. It sets itself up to be an HTTP client by doing the following: 

i. Calls IntemctOpenO to get a handle to the internet session 

c. For each service it exposes, it does the following: 
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i. It calls the SSDP API RcgistcrUpnpEventSourcc() to let the SSDP server 
know that it will be accepting subscriptions and sending event 
notifications. At this point, it has no subscribers. Note that this is called 
before the service has announced itself so that it can be ready to accept 
5 subscriptions immediately. RegisterUpnpEventSourceO sends no 

15 

network traffic on the wire. It is a local initialization only. 
RegisterUpnpEventSourceO does the following: 

1 . Adds a structure to the list of event sources containing the 
20 following: 

10 a, A URL to which subscribers will send subscription requests 

b. A list of destination URLs. A notification message will be 

sent to each destination URL. 

25 

c. The state table for the event source. This structure contains 
the property name, value, and type for each property 

1 5 supported by the service. 

2Q ii. It calls the SSDP API RegisterServiceO to let the world know that it has 

become available. RegisterService() will send out an SSDP "alive" 
message on the multicast channel that will be heard by any device 
running the SSDP service. 
20 d. It starts sending events immediately, even without subscribers. Each event 

submission updates the local state table. This submission needs to be atomic 
with regard to adding subscribers, so between the time the SubmitEvcntQ API 
^ is called, and the time the local state table is updated, no subscriptions can be 

added or removed. 
25 2. Meanwhile, a UPnPUCP initializes. 

a. It initializes its HTTP server, passively listening on a TCP port. 

45 
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25 



b. If the UCP started up before the UPnP device initialized, it won't see any 
^0 services become available. When the device fuialJy starts* the UCP will be 

notified. 

c. Once the UPnP services have been announced the UCP will be able to access 
5 one or more of them. 

d. The UCP drives the UPnP API to instantiate a UPnP Service Object, 
c. The UPnP Service Object does the following when it is instantiated: 

i. It obtains the event subscription URL from tlie description for that 
20 service. 

10 ii. It calls the SSDP API RcgistcrNotificationO specifying 

SSDP_PROPCHANGE as the event type, the event subscription URL, a 
callback function pointer (which is a static member function of the 
class), and a context pointer (which is the '*this" pointer of the class). 
RegisterNotificationO does the following: 
15 1 . tt makes an LRPC call to the SSDP service. The rest happens on 

the service side. 

2. If this is the first time it is called for SSDP_PROPCHANGE 
notifications, RegisterNotificationO call IntcmctOpcn() to get 
a handle to an internet session. This handle is shared among ail 

35 20 local UPnP UCPs. 

3. It calls IntemctConncctO passing the server name given in the 
URL it was passed. 

4. It calls HttpOpenRequestO passing in the rest of the URL it was 

40 

passed. 

25 5. The handles returned by these functions are saved with the 

structure that maintains the subscription. 
45 6. It composes a SUBSCRIBi^ message, using the data passed in, by 

calling HttpAddRequestHeadersO- It adds the "NT'. "Callback", 
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and '"Timeout" headers. The Callback header of the SUBSCRIBE 
10 message will be composed on the fly, as an arbitrary URL for 

notifications to be sent to for this subscription. The server name is 
the local IP address, and the port is the same one referred to by 
5 step 2a above. 

15 

7. It calls HttpSendRequestO to send the request to the CD. This is a 
synchronous function that will return when the request has been 
responded to by the CD. 

20 . 8. It calls HttpQueiyInfo(. . HTTP_QUERY_CUSTOM, . . .) to get 

1 0 the "Subscription-Id" header The resulting SID will be stored with 

the subscription structure. 
9. It calls HttpQueryInfo(..., HTTP_QUERY_CUSTOM, ...) to get 

25 

the "Timeout" header. The resulting timeout value will be stored 
with the subscription structure, 
15 1 0. A timer is started for re-subscription based on the timeout value 

returned in the response. When the timer goes off, the re- 
subscription will be sent, 
1 1 . The SID, callback function pointer, and timeout values are stored 
in a structure that maintains the lisi of local subscriptions. 
35 20 3. Back on the UPnP CD, the subscription request is received by the HTTP server. The 

following occurs: 

a. The request is parsed into URI, NT, Callback, and Timeout fields. 

b. The NT field must match "upnp:event'V If it doesn't, the CD responds with 

40 

"412 Precondition Failed." 
25 c. The URI identifies the event source. The URI is converted into a URL and 

matched with the list of event sources registered on the CD. If no match is 
45 found, the CD responds with "404 Not Found". 

d. If a match is found, the following occurs: 
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i. The Callback URL is added to a list of subscriber URLs. 

ii. The Timeout value is processed and an absolute time is stored \^"ith the 
event source data. If this time expires and a re-subscribe message has not 
been received, the subscription is removed. 

5 iii. A new SID is created, and stored with the subscriber in the event source. 

15 

iv. A sequence number is initialized to 0. 

V. A subscription response is composed, including an echo of the Timeout 
header and the SID just created. 
20 vi. The response is sent. 

10 vii. If the response is sent successfully, the list of event sources is persisted 

to disk for recovery purposes, 
viii. A timer is started using the same timeout value as the header echoed to 
the UCP. When this timer elapses, the subscriplion is removed. If the CD 
receives a re-subscribe request, this timer will be reset. In an idea! world, 
1 5 the timer will never elapse. 

ix. An initial event notification is sent to initialize the UCP's state table. The 
following describes that process: 

1 . IntemetOpenO is called if an existing internet session handle does 
not exist. 

-'^ 20 2. IntemetConnectQ is called, passing the server name specified in 

the callback URL for this subscription. 

3. HitpOpenRequestO is called, passing in the rest of the callback 
URL, 

40 

4. A NOTIFY message is composed, using the data passed in, by 
25 calling HttpAddRequestHeadersQ. It adds the "Nrr\ "NTS", 

"SID", "Seq", "Content-Length", and "Content-Type" headers. 
45 a. The NT header will always be "upnp: event". The NTS header 

will always be **UPnP:propeTtychange'V 
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b. The SID header contains the SID stored in the event source 
10 structure 

c. The Seq header will always be 0. 

d. The Content-Length header will be the number of bytes in the 
5 XML body. 

15 

e. The Content-Type header will always be "text/xml". 

f. The body of the message is composed from the list of 
properties stored within the event source structure: 

2Q i- Write the <propertyset> opening tag. 

10 ii. Write the <propcount>/i</propcount> tag. UTicre n is 

the number of total properties. 

iii. For each property: 

1 . Write the <property> opening tag. 

2. Write the <prop> opening tag, where prop is the 
1 5 name of the property. 

3. Write the <type>rv/»e</typc> tag, where type is 
the stringized type name of the property type. 

4. Write the property value. 

5. Write the <Jprop> closing tag. 
35 20 6. Write the </propeity> closing tag 

iv. Write the </propertyset> closing tag 

5. It calls HttpScndReqwstExO, then IntemetWriteFile(), then 
HttpEndRcquestQ to send the request to the CD. 

6. The response is ignored except for debugging purposes. 

25 4. The UPnP CD now is ready to send an event notification. It does this by calling the 
SubmitUpnpPropertyEventO API. The following occurs inside that API: 
^5 a. The event source handle is converted to an event source structure. 
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b. The properties that have changed as a result of the event are passed into the 
^0 funciion and updated in the local list of properties slored v\'ith the event source. 

c. For each subscriber, the following occurs: 

i. IntemetConncctO is called, passing the server name specified in tlie 
5 callback URL for this subscription. 

15 

ii. Ht^OpcnRequestO is called, passing in the rest of the callback URL. 

iii. A NO TIFY message is composed, using the data passed in, by calling 
HttpAddRequestHeadersQ. It adds the * *OTS". "SID'\ "Seq", 

20 "Content-Length", and "Content-Type" headers. 

10 I . The NT header will always be "upnp: event". The NTS header will 

always be "UPnP:propertychange". 

2. The SID header contains the SID stored in the event source 
structure 

3 . The sequence number for the event source is incremented and the 
1 5 Scq header is created with this value. 

4. The Content- Length header will be the number of bytes in the 
XML body. 

5. The Content-Type header will always be "text/xml". 

6. The body of the message is composed from the list of properties 
^5 20 stored within the event source structure: 

a. Write the <propertyset> opening tag. 

b. Write the <propcount>/i</propcount> tag. Where « is the 
number of total properties. 

c. For each property that has been submitted: 
25 i. Write the <property> opening tag. 

ii. Write the <prop> opening tag, where prop is the name 
45 of the property-. 
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iii. Write the <typc>type<type> tag, where type is the 
10 slringized type name of the properly type, 

iv. Write the property value. 

V. Write the <Jprop> closing tag. 
5 vi. Wrile Ihc </pruperty> closing tag 

15 

d. Write the </propertyset> closing tag 
iv. SubmitEventQ is called, passing the event source handle, the handle to 
the headers created by 4c(i) Ihru 4c(iii) above, and the body created in 
2Q step 4c(iii)6. SubmitEventQ does the following: 

10 1 . It calls HttpSendRequestExQ, then IntcmetWriteFiIe() on the 

body, then HttpEndRequestQ to send the request to the CD. 
2. The response is ignored except for debugging purposes. 
5, The UPnP UCP receives the notification message. The message is processed as 
follows: 

1 5 a. The HTTP server receives a NOTIFY message with a Requcst-URI and 

several other headers. 

30 

b. The NOTIFY message b parsed, looking at the ^'NT*' header firsL If this 
header contains *'upnp:event", then the message is further processed for event 
notifications as follows: 

35 20 i. The message is parsed for the >rrS header. If that contains 

'*upnp:propert>'changed", then the message is parsed further as follows: 

1. The message is parsed for the SID header. The SID indicates to 
the UPnP control point which subscription this message applies to. 

2. The message is parsed for the "^eq" header. If this header 
25 contains a value of 0, the UCP knows this is an initial state 

populate request. If the local sequence number is exactly one less 
45 than the Seq header, the local sequence number is updated 

(incremented), and the message is processed further. 
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3 . The Request-URI can be ignored, since the HTTP server knows 
^0 all NOTIFY messages with an N T header of "upnp:evenl" are ^nt 

to the same Request-URI. 

4. If the Seq header contains a number that is not exactly one more 
5 than the local sequence number, tlie UCP knows it has missed an 

15 

event. In this state, it needs to unsubscribe and re-subscribe to the 
event source in order to re-sync its state. 

5. The SID is matched against the list of subscriptions maintained on 
20 the UCP. When the SID is matched, its associated callback 

10 function is invoked. 

6. The callback function is passed an SSDP_MESSAGE structure 
which contains all the relevant headers and the body of the XML 

25 

message received. 

7. The callback function is implemented by the UPnP API, as a static 
1 5 member of the Service object. When this function is called, the 

2^ following occurs: 

a. The body of the message is parsed using the XML DOM 

services. 

b. As properties are enumerated, their values are stored in the 
35 20 local state table for the service. 

c. An event is fired to all high-level clients of the UPnP API. 

This event contains the list of properties that have changed 
and their new values. 

6. The re-subscription timer for one of the UCPs subscriptions expires. The following 
25 occurs: 

a. A re-subscribe message is composed. This message is very similar to a 
45 subscribe message except in doesn't include an NT or Callback header, but it 

does have a SID header. 
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b. The request is sent to the CD. 

c. The response contains the new timeout value. 

d. The timer is reset with this timeout. 

UCP State Synchrofiization Models 

5 CD-Initiated NeedsSync method 

This method begins with the CD sending its initial state to the subscriber the 

first time an event is submitted by the service. UCPs will subscribe to the service fu-st, 

then receive notifications for events as they occur. The first event will happen to be the 

initial state of the service. The UCP state tabic will always be in sync with this method. 

10 When the CD sends a notification to a subscriber and receives an error. In this 

case, it marks the subscriber as "NeedsSync" and the next time an event is submitted, 
all events are sent to the subscriber. The problem with this is that the API needs to keep 
track of which subscribers need syncing and which ones don't. The client of this API 
(the UPnP service) would need to send separate messages to each subscriber and know 

15 uliich ones needed all events and which ones just wanted the ones that changed. 

UCP'initiated sync 

This method states that the UCP should subscribe to event notifications, then 
call a fiinction that obtained the state from the service. This means that any events that 
were received in the meantime would need to be matched against the incoming set of 

20 events and replaced if they were older. This method leads to synchronization issues 
where the UCP may receive events that arc newer but when it queries for the state, it 
gets an older view of the table. This requires using sequence numbers to determine 
which information is newer. If the view of the table received by the query is too old, it 
has to be discarded. Alternatively, the properties that were not received by event 

25 notification would not be overwritten, but all other properties would be. Using 
sequence numbers make this more complicated. 
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CD-initiated sync 

10 This preferred meLhod takes a simpler approach. Any time the UCP subscribes 

to a service, the service will immediately afterwards, send the entire contents of the 
state table with the first notification. This precludes the UCP from making a query for 
5 the state table. Subsequent events update the local state table on the UCP. If. the 

15 

connection is lost, the UCP will lose its subscription. If the UCP realizes it has not 
received an event after a certain amount of time has elapsed, it will re-subscribc. At 
that point, the CD will re-send the entire state table again, and the UCP is ensured to be 
20 up to date. 

10 Exemplary Computer Hardware 

Figure 24 and the following discussion are intended to provide a brief, general 
25 description of a suitable computer which may be used in the above described UPnP 

device control model. This conventional computer 820 (such as personal computers, 
laptops, palmtops or handheld-PCs, set-tops^ servers, mainframes, and other variety 
15 computers) includes a processing unit 821 . a system memory 822, and a system bus 823 
that couples various system components including the system memory to the processing 
unit 821. The processing unit may be any of various commercially available 
processors, including Intel x86, Pentium and compatible microprocessors from Intel and 
others, including Cyrix, AMD and Ncxgcn; Alpha from Digital; MIPS from MIPS 
20 Technology, NEC, IDT, Siemens, and others; and the PowerPC from IBM and 

Motorola. Dual microprocessors and other multi-processor architectures also can be 
used as the processing unit 82 1 . 
^ The system bus may be any of several types of bus structure including a memory 

bus or memor>' controller, a peripheral bus, and a local bus using any of a variety of 
25 conventional bus architectures such as PCI, VESA, AGP, MicroChannel, ISA and EISA, 
to name a few. The system memory includes read only memory (ROM) 824 and 
random access memory (RAM) 825. A basic input/output system (BIOS), containing 
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the basic routines that help to transfer infonnation between elements within the 
10 computer 820, such as during start-up, is stored in ROM 824. 

The computer 820 further includes a hard disk drive 827, a magnetic disk drive 
828, e.g., to read from or write to a removable disk 829, and an optical disk drive 830, 
5 e.g., for reading a CD-ROM disk 83 1 or to read from or write to other optical media. 
The hard disk drive 827, magnetic disk drive 828, and optical disk drive 830 are 
connected to the system bus 823 by a hard disk drive interface 832, a magnetic disk 
drive interface 833, and an optical drive interface 834, respectively. The drives and 
2Q their associated computer-readable media provide nonvolatile storage of data, data 

10 structures, computer-executable instructions, etc. for the computer 820. Although the 
description of computer-readable media above refers to a hard disk, a removable 
magnetic disk and a CD, it should be appreciated by those skilled in the art that other 
types of media which are readable by a computer, such as magnetic cassettes, flash 
memory cards, digital video disks, Bernoulli cartridges, and the like, may also be used 
1 5 in the exemplary operating environment. 

A number of program modules may be stored in the drives and RAM 825« 
including an operating system 835, one or more application programs 836, other 
program modules 837, and program data 838. 

A user may enter commands and information into the computer 820 through a 
35 20 keyboard 840 and pointing device, such as a mouse 842. Other input devices (not 

shown) may include a microphone, joystick, game pad, satellite dish, scanner, or the 
like. These and other input devices are often connected to the processing unit 82 1 
through a serial port interface 846 that is coupled to the system bus, but may be 
connected by other interfaces, such as a parallel port, game port or a universal serial bus 
25 (USB). A monitor 847 or other type of display device is also connected to the system 
bus 823 via an interface, such as a \'ideo adapter 848. In addition to the monitor, 
45 computers typically include other peripheral output devices (not shown), such as 

speakers and printers. 
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The computer 820 operates in a networked environment using logical 
connections to one or more remote computers, such as a remote computer 849. The 
remote computer 849 may be a server, a router, a peer device or other common network 
node, and typically includes many or all of the elements described relative to the 
computer 820, although only a memory storage device 850 has been illustrated in 
Figure 24. The logical connections depicted in Figure 24 include a local area network 
(LAN) 85 1 and a wide area network (WAN) 852. Such networking environments are 
commonplace in offices, enterprise-wide computer networks, intranets and the Internet. 

When used in a LAN networking envirotmient, the computer 820 is connected to 
the local network 85 1 through a network interface or adapter 853. When used in a 
WAN networking environment, the computer 820 typically includes a modem 854 or 
other means for establishing communications (e.g., via the LAN 851 and a gateway or 
proxy server 855) over the wide area network 852, such as the Internet Tlie modem 
854, which may be internal or external, is coimected to the system bus 823 via the serial 
port interface 846. In a networked environment, program modules depicted relative to 
the computer 820, or portions thereof, may be stored in the remote memory storage 
device. It will be appreciated that the network connections shown are exemplary and 
other means of establishing a communications link between the computers may be used. 

In accordance with the practices of persons skilled in the art of computer 
programming, the present invention is described below with reference to acts and 
symbolic representations of operations that are performed by the computer 820, imless 
indicated otherwise. Such acts and operations are sometimes referred to as being 
computer-executed. It will be appreciated that the acts and symbolically represented 
operations include the manipulation by the processing unit 821 of electrical signals 
representing data bits which causes a resulting transformation or reduction of the 
electrical signal representation, and the maintenance of data bits at memory locations in 
the memory system (including the system memory 822, hard drive 827, fiojjpy disks 
829, and CD-ROM 83 1) to thereby reconfigure or otherwise alter the computer system's 
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operation, as well as other processing of signais. Hie memory locations where data bits 
are maintained are physical locations that have particular electrical, magnetic, or optical 
properties corresponding to the data bits. 
Exemplary Embedded Computing Device 
5 Figures 25 and 26 are intended to provide a brief, general description of a 

15 

suitable embedded computing device 900 which may be used in the illustrated 
implementation of the invention. The embedded computing device 900 can be any 
variety of device incorporating electronics to control operational functions (operational 
20 circuitry 906), and in which computing and networking capabilities are embedded. For 

1 0 example, devices in which computing and networking functions can be embedded 
include communications devices (e.g., telephones, cell phones, audio and video 
conferencing systems, 2-way radios, etc.), office equipment (printers, fax machines, 

25 

copiers, dictation, etc.)t audio- video equipment (audio and video recorders and players, 
including televisions, radio receivers, compact disk (CD), digital video disk (DVD), 
1 5 camcorders, etc.)t etitertaixuncnt devices (set-top boxes, game consoles, etc.)* 
2Q environment cotitrol equipment (them:iostats, heating/ventilation/air-conditioning 

equipment, light switches, etc.), security systems, home appliances (coffee makers, 
dishwashers, clothes washer/dryer), automobiles, public facilities equipment (signs, 
traffic signals, etc.), manufacturing equipment, and many others. 
20 With reference to Figure 25, the device 900 includes a processing unit 902, and 

a memory 904 to provide embedded computing capability. The processing unit 902 has 
hardware interfaces to the operational circuitry 906 that operates devices functions. The 
^ processing unit 902 can be a microprocessor or micro-controller, such as are available 

from Intel, Motorola, IBM, and others. Ths memory 904 preferably incorporates RAM 
25 and ROM to hold software and data for basic operating code as well as for user 
applications. 

45 The device 900 also includes a network adapter 908 for connecting with a 

network media 910 that is interconnected with the computer network in which the 
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authoritative names Tcgistry (described below) is implemented in accordance with the 
invention. The network adapter 908 can be a network interlace card (or chip set 
integrated on a single board with the processing unit 902) appropriate to the particular 
network media 91 0. The network media can be any of various wired or wireless 
5 network media, including Ethernet, IEEE 1394 (a,k.a. fircwire), radio frequency 

(including satellite, cell, pager, commercial signal sidebeuid, etc.), power line carrier 
(PLC), phone line, and television cable, among others. 

With reference now to Figure 26, the embedded computing device 100 (Figure 
25) has a software architecture 1 20 that conforms to the above described IJPNP device 

10 control model. UPN? provides a mechanism for the embedded computing device to 
operate in the Internet, as well as networks that have no administrator and no 
connection to the Internet, and hence no accefu to configuration ser\'ices like the 
Dynamic Host Configuration Protocol (DHCP). DHCP is a mechanism for providing 
devices with configuration information needed to access the Internet. The mechanism 

1 5 ftinctions through the use of a multicast request for configuration information that is 
generally responded to with an IP address and DNS server location. Additional 
information can only be returned in the response. 

In non-configured (ad-hoc) networks, UPNP uses the AutoIP protocol. AutoIP 
is an enhancement to DHCP that allows devices to claim IP addresses in the absence of 

20 a DHCP server or similar IP configuration authority. IP addresses arc claimed &om a 
reserved rsuigc that is not allowed to be transmitted on the open Internet; thus they are 
only good for the local network. The embedded computing device 1 00 claims an 
address by randomly generating an address in the reserved range and then making an 
ARP request to see if anyone else has already claimed that address. AutoIP systems 

25 will continually check for the presence of a DHCP server so that if one should ever 
come online, all the AutoIP devices will attempt to switch their IP addresses to one 
provided by the DHCP server. This allows a network to operate in isolation, be 
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connected to the Internet with DHCP support and then to be returned to isolation. This 
type of scenario will be common in homes that use dial-up access. 

The UPNP protocol also uses Multicast DNS for addressing the embedded 
computing device 900. The Internet Domain Name System (DNS) is a mapping system 
5 thai translates human readable domain names, like microsoft.com, into their equivalent 
IP address. Most corporate intranets implement an interna] version of the same 
technology to provide the same services, in small networks, such as at home or in small 
business, DNS servers may not exist. Multicast DNS allows DNS requests to be 
multicast. This allows a machine to see requests for its own name and respond to them. 

10 Like AutoIP, Multicast DNS is only used when a DNS server is not available. (For 

more information, see B, Woodcock, Zocoio, and B. Manning, Multicast Discovery of 
DNS Services , IETF Internet Draft, "drafl-manning-multicast-dns-OI.txt.".) 

UPNP implements a peer discovery mechanism that uses the Simple Service 
Discovery Protocol (SSDP) for discovery of devices on IP networks. 

1 5 SSDP is based on profiles. A single identifier specifies a profile that defines a contract 
between the client and service (e.g., operational functions provided by the embedded 
computing device). By identifying itself with the profile, the service advertises 
compliance with the associated contract. 

Using a single identifier makes it possible to implement an extremely simple discovery 
20 system. Clients send out a User Datagram Protocol (UDP) multicast packet containing 
the identifier of the desired service on some standard channel. Services listen on the 
standard channel, read the request, see whether they provide the service, and respond if 
so. 

UPNP also provides a Directories mechanism to allow discovery to scale - to the 
25 entire Internet if needed. When present, a directory will read all incoming service 

requests and respond to them itself. This requires that all services (e.g., the embedded 
computing device. 900) register with the directory so that the directory is able to 
properly answer on their behalf. The directory is also responsible for commxmicating 
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with other directories in order to determine whether the serv ice is available within the 
local network* the WAN and potentially the Internet. 

To simplify the discovery protocol, directories are treated as proxies. A proxy is 
a service that accepts requests and takes responsibility for finding the proper response. 
5 When a client comes online, it will perform discovery for the proxy. If the proxy is 

present, then the client will send all future discovery requests to the proxy. If the proxy 
isn't present, then the client will send all discovery requests to the reserved discovery 
multicast channel. Regardless of the presence of a proxy, the client's request format and 
procedures will always be the same. The only difference will be the address to which 

1 0 the client sends its requests. For services, the difTerence between a proxied and 

unproxied network is their need to answer discovery requests. On a proxied network, 
services need do nothing once they have registered with the proxy. On an unproxied 
network, they answer discovery requests directly. 

SSDP uses the UDP- and Transmission Control Protocol (TCP)-based 

1 5 Hyptertext Transport Protocol (HTTP) to provide for service discovery. SSDP uses a 
Uniform Resource Identifier (URI) to represent the service and the OPTIONS method 
to provide for discovery. SSDP also will provide support for proxies. These proxies, 
which are really Just fronts for directories, redirect discovery requests to themselves. It 
is the proxy's job to collect aimounce requests in order to determine what services are 

20 available as well as to communicate with other proxies in order to provide for scalable 
service discovery. 

The discovery process returns only the basic information needed to connect to 
the embedded computing device. Once a service has discovered its peers, the service 
often needs to find out more informatioa in order to work best with them. The 
25 description process returns a schema providing descriptive data about the service. 

A schema is a structured data definition that defines a set of structured values 
that provide descriptive informadon about a service. UPNP uses the Extensible Markup 
Language PCML) for schema, because XML's self-describing structured data format 
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provides the level of expressiveness and extensibility needed by a universal schema and 
10 data format. 

Accordingly, UPNP supports automatic network introduction, meaning that 
devices and their related services have the ability to be self-describing and allow 
5 automatic configuration. When a device is plugged into the computer network, the 
device automatically configures itself and acquires a TCP.'TP address. The device then 
announces its presence to other devices already on the network using a simple discovery 
protocol based on the Intemet HTTP protocol and is immediately ready to share its 
20 services with any device that requests them. 

1 0 With UPNP, device developers arc not required to develop specific device 

drivers to operate under UPNP. The task of preparing a device for operation in this 
network environment thiis is fairly simple. Moreover, in configured networks, dynamic 
detection allows an operating system to immediately begin using added devices or stop 
using removed devices without rebooting. 
15 UPNP Devices support automatic discovery, identification, and configuration to 

achieve interoperability in the home environment, but must also operate correctly in a 
managed corporate network. Devices can be networked instead of being attached 
directly to a PC, and devices are all autonomous citizens on the network, able to talk 
with each other and exchange information. UPNP provides a unified way of performing 
35 20 directory services with automatic configuration. Capability for simple discovery 

mechanism used in the home environment provides the ability for any device to become 
a node on the global Internet. Additionally* directory ser\'ices can be leveraged if they 
are available in the corporate environment. 

40 

UPNP provides a common set of interfaces for accessing devices and services, 
25 enabling the operational unification of diverse media types. Commimications protocols 
for Universal Plug and Play are based on industry standards, especially key Intemet 
45 standards such as TCP/IP, HTML, XML, HTTP, DNS, LDAP, and others. Individual 

implementations for particular networks and buses are built on established protocols. 
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As shown in Figure 26, the software architecture 920 of the embedded 
computing device 900 (Figure 25) includes the following soRware code modules that 
implement UPNP: device functions 922, simple discovery 924, Hypertext Transport 
Protocol (HTTP) 925, Transmission Control Protocol/Internet Protocol (TCP/IP) stack 

5 926, Autonet 928, Dynamic Host Configuration Protocol (DHCP) 930, and physical 
media 910 (also shown in Figure 25), The device functions 922 is a software code 
module to implement the device's functionality. For example, where the embedded 
computing device is a VCR, the device functions code can include code to implement 
start, stop, pause, record and other functions that the VCR can perform. 

0 The simple discovery 924 is a software code module (about 4 Kbytes) that 

implements a simple discovery procedure (described below) for automatic network 
introduction under the UPKP protocol. 

The simple discovery procedure additionally provides an Extensible Markup 
Language (XML) format device description, which is downloaded to clients that access 

5 the device to allow activation of device functionality &om the client. XML is a textual, 
tag -based markup language. It was originally designed to be the "webby" simplification 
of SGML (Standard Generalized Markup Language), and is therefore intended to he 
used to create "vocabularies" of tags that can be used to apply semantic markup to 
documents, such as who the author was, what constitutes a paragraph (semantically, not 

iO from a display point of view), when the author last had breakfast, and so on. (For more 
infomiation, see A. Layman, E. Jung, £. Maler, H. Thompson, J. Paoli, J. Tigue, N. H. 
Mikula, S. De Rose, "XML-Data", W3C Note, "NOTE-xml-data-0105".) In the context 
of UPNP, XML is used to provide the description of services and capabilities of the 
embedded computing device. The embedded computing device makes its features 

15 visible to clients by providing its XML device description, which the client can use to 
activate device functions 922. For example, if the device is a camera, the client's 
browser can direct the camera to zoom in/out or adjust contrast using the mechanism of 
XML- 
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The XML device description can provide links (via a uniform resource locator 
or URL address) to an accompanying XSL format style sheet. The XSL style sheets are 
used to present the data in different ways, i.e., the style sheets are applied to present 
different views of the same data. For example, if the device contains a file system, one 
5 style sheet can show the tlie selections; another shows the file sizes in some sort of 
diagram; yet another style sheet could make thumbnails of these image files. 

The HTTP 925 is a software code modules (about 20 Kbytes) that implements 
the standard HTTP protocol, which is an open standard mechanism for client/server 
message-based communication. HTTP provides for proxying, contcm negotiation and 
10 security. [For more information, sec R. Fielding, J. Gettys, J. Mogul, H. Frystyk, T. 
Bemers-Lee, Hypertext Transfer Protocol - HTTP/1 . 1 , IETF RFC 2068 (January 
1 997).] The TCP/IP stack 926 implements the standard TCP/TP networking protocols 
for communication on the computer network. The Internet Protocol (IP) is the 
foundation protocol of the Internet. It defines how a single message is sent from a 
1 5 source through zero or more routers to its final destination. It covers issues such as 
message lengthy message fragmentation, addressing, and routing concerns. The 
Trdnsmission Control Protocol (TCP) is an IP-based protocol that provides support for 
the reliable, ordered delivery of messages over IP. Additionally, User Datagram 
Protocol (UDP) and Internet Group Management Protocol GGMP) multicast send/listen 
20 capability are included in the implementation. 

The Autonet 928 is a software code module also used for automatic network 
introduction via AutoIP in the UPNP protocol. Autonet uses a predefined set of IP 
addresses and, when a device is connected to the network, it pings an address in this 
address space. If it gets no replies, the device assumes that the address is available and 
25 assigns it to itself. To make this functionality even more useftxl it is combined with 
Multicast DNS, in which the device itself holds its own name. Thus it is not even 
necessary to determine what IP address the device assigned to itself, because its name 
can always be used instead. An IP Multicast is a mechanism for sending a single 
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message to multiple recipients. IP multicasting is especially useful for discovery 
^0 operations where one does not know exactly who has the information one seeks. In 

such cases, one can send a request to a reserved IP multicast address. Any services that 
can provide the requested information will also subscribe to the multicast request and 
5 thus be able to hear Ihc informaLion request and properly respond. Multicast DNS is a 
proposal to the IETF on rules for making normal DNS requests using multicast UDP. 
(For more information, sec B. Woodcock, B, Manning, Multicast Discover^^ of DNS 
Services , IETF Intemet Draft. "draft-manning-multicasL-dns-01.txt".) 
20 The DHCP 930 is a software code module that implements the Dynamic Host 

1 0 Configuration Protocol (DI ICP), which is a mechanism for providing devices with 
configuration information needed to access the Intemet. The mechanism functions 
through the use of a multicast request for configuration information that is generally 
responded to with an IP address and DNS server location. Additional information can 
only be returned in the response. 
1 5 Figures 27 and 28 show processes 934, 940 per the UPNP protocol for automatic 

network introduction of the embedded computing device 900 (Figure 25) into an ad hoc 
(where the device does not have a configured IP address) and a configured computer 
networic environment, respectively. The automatic network introduction process 
establishes an appropriate configuration (e.g., with an IP address) of the embedded 
20 computing device upon connection to a server computer on a computer network, so as 
to enable access to the device from a client. The processes 934, 940 involve five 
phases: aimounce, discovery, response to discovery, autonet, and device description. 

At the announce phase, the embedded computing device 900 sends out a small 
multicast packet so that other devices can find it on the network. The multicast message 
25 packet essentially says, "I am here, I am, (say), a camera, and you can reach me at this 
IP address or URL." 

45 
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At the discovery phase, the embedded computing device 900 listens for a 
discovery packet coming from a simple discovery client, i.e., the device announces 
itself, then listens for discovery. The discovery packet also is sent out by multicast. 
At response to discovery, the embedded computing device 900 listens to the 
5 multicast address and then parses the informatioa from a Simple Discovery request to 
decide if the request is for its kind of device. If so, the device 100 then sends back a 
response packet containing the following information: the IP address or URL where ii 
can be reached; identification of its own device type; and the discovery packet ID so the 
20 requesting client knows which request is being answered. 

10 At the Autonel phase, the Autonel module 928 of the embedded computing 

device 900 uses a predefined set of IP addresses and, when the device is connected to 
the network, it pings an address in this address space. If no reply is received, the device 

25 

900 assumes that the address is available and assigns it to itself. Alternatively, the 
device 900 may combine Autonet with Multicast DNS, and itself hold its own name. In 

1 5 which case, it is not necessary to determine what IP address the device assigned to 
2Q itself, because its name can always be used instead. 

Both the Annoxmce and Discovery packets also contain a link or a URL to an 
XML file that is used by the embedded computing device at the device description 
phase to describe itself (i.e., its functionality). This XML data contains all the facts 

20 about the device. XML can also have URLs that point to appropriate style sheets (XSL 
files) that are used for optimal presentation. The XSL style sheets are used to present 
the data in different ways. I.e., the style sheets are applied to present different views of 
the same data. For example, if the device contains a file system, one style sheet can 
show the file selections; another shows the file sizes in some sort of diagram; yet 

25 another 5ttylc sheet could make thumbnails of these image files. 
Exemplary Client 

45 With reference now to Figure 29, a client that accesses and uses the embedded 

computing device 900 over the computer network has an exemplary client software 
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architecture 950, which includes software code modules for applications 952, simple 
^0 discovery 954. XML 955, LDAP 956, TCP/IP stack 958 and a network interface card 

(NIC) 960 that provides a physical connection to the computer network. The 
applications 952 is a software code module that provides a user interface features for 
5 locating desired devices (e.g., embedded computing device 900) and services on the 
computer network, and also user interface features to interact with the located device or 
service. The applications 952 can include an Internet browser, such as the Microsoft 
Internet Explorer, that can present the XML device description in accordance with an 
20 associated XSL st>'le sheet for interaction with the embedded computing device and 

10 activation of its operational functionality. 

The simple discovery 954 is a module that implements the above-described 
simple discovery* per the UPNP protocol. The XML 955 is a module that processes the 
XML device description and XSL style sheets for presentation in the application's user 
interface. The LDAP 956 implements the standard LDAP directory protocol for name 
1 5 look-up. The TCP/IP stack 958 implements the TCP/IP protocol for communications 
over the computer network. 
Illustrative Pervasive Computing Environment 

Figure 30 illustrates a pervasive computing environment 1000, such as may be 
installed in a home, office or public place, which includes a large number of embedded 
35 20 computing devices, such as the illustrated device 900 (Figure 25). The pervasive 

computing environment 1000 includes personal computers 1002, 1004 (e.g., of the iyp€ 
shown in Figure 24) connected via a local area network (LAN) 1006. The PC 1002 is 
connected via a imiversal serial bus 1016 to a telephone modem 1010, XDSL interface 

40 

1011 or a cable modem 1012, which in turn provide a connection with the computer 
25 network, e.g., the Internet. 

Various embedded computing devices also coimect to the computer network via 
45 various network connections to the PCs 1002, 1004. These include an audio device 

1014 (e.g., speakers, radio tuner, microphone), and printer 1015 which connect to the 
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PC 1004 through a USB 1017. Also, a digital camera 1020, a handheld PC (H/PC) 
1 02 1 and another personal computing device 1 022 connect via an infrared port (IRDA) 
1024, which also attaches to the PC 1004 through the USB 101 7. Also, lighting 
switches 1030 and like home appliances are connected via an A/C power line-based 
5 networking 1 032 to the PC 1002. Further, a chain of IEEE 1 394 cables 1 048 connect a 
digital TV 1040, DVD player 1041, digital video camcorder (DV/DVC) 1042, an audio 
device 1043 (e.g., CD player/recorder, radio receiver, amplifier, and like audio system 
component), and a game console 1044. Devices, such as a portable telephone 1050 and 
remote control 1051, have a radio frequency network connection with the PC 1004. 
1 0 With their various inter-networked connections, the embedded computing 

devices are "visible" and accessible from a client device 950 (Figure 30) aJso connected 
to the computer network. 

Contract Definition Langtiage 



other entities on the Web (reachable via HTTP, mostly) or other computer network that 
react to and emit messages. The Contract is written in a Contract Definition Language 
(CDL). The messages for the most part are structured documents, e.g., in XML. The 
messages may also be HTML pages, streaming media, images or other datatypes 
20 appropriate to the WebObject. 
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Overview 

Contracts describe the public behavior of UPnP devices, and alternatively of 



The contract will describe the following attributes of a WebObject: 

• end-point (wcll-dc fined name) 

• protocol 



• messagmg patterns 



25 



• delivery characteristics 

• pavloads 
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All of these attributes may not be present in the contract as some of them (the 
10 end-point, for instance) may not be available at development time. 

Protocol description 

WebObjects can be accessed using multiple protocols: HTTP, GEN A, SMTP, 
5 FTP, MSMQ, ... This section discusses how to describe the protocol bindings particular 
to a WebObject. The templates for describing the protocol use the format: 



15 



<protocol> 

<HTTP> 

// HTTP specific settings go here 
20 1 0 </HTTP> 

-<;/protocol> 
<protocol> 

<HTTP> 

// GENA specific settings go here 
25 15 </HTTP> 

<;/protocol> 



30 

20 detail below. 



35 



The "protocol" element may have an "id" attribute. This is useful when multiple 
messaging patterns will use the same protocol definition. This will be covered in more 



For the sake of convenience, we only cover HTTP-based protocols here. 
Extending this model to cover the other protocols is straightforward, 

HTTP 
GET 



25 <protocol> 

<HTTP version-" 1.0"> 
^ <GET/> 



<URI> http://l 72.30. 1 84. 20/fiill si 7c.jpg 
</URL> 

30 </HTTPx/protocol> 



45 GET with query string 

<protocol> 
<HTTP version="l.r> 
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<GET/> 

<URL> http://search.yahoo.comy'bin/search </URL> 
<QUERY name="pauem" required- "yes" /> 
<QUERY name="liinii" value="50" required="iio" /> 
5 <QUERY name="xmr' value="yes" required="yes" /> 

</HTTP> 

</protocol> 

15 

TTiis description indicates that the following are valid URLs: 
1 0 http://scarch.yahoo-coni/bin/scarch?pattem'=Rio4player&limit=50&xinl==ycs 
http://seaTch.yahoo.com/bin/search?xml=yes&pattem=Rio+player 
The reason for not associating the quer>' variables with the GET verb is because 
it is valid to send a POST message to a URL containing query variables. 

The "value" attribute for the "QUERY" element implies that the value is static — 
15 it is to be treated as a part of the URL. Declaring it this way allows the appropriate 
construction of the query string to be handled by the caller. 



25 



POST 
<protocol> 

30 <HTTP version=" 1 . r> 

20 <URL> http://www.amazon.com/cxcc/obidos/gcncric-quicksearch- 

qucry </URL> 
<POST^ 

<PARAM name="mode" default-'blended" required=''yes" /> 
35 <PARAM name-^keyword-query" requircd="ycs" /> 

25 <PARAM name="zipcode" value="98 1 12" rcquircd="yes" /> 

</POST> 
</HTTP> 

</pTOtOCOl> 

40 

30 The default attribute indicates that the parameter's value can be changed. 

M-POST 

<protocol id="protocolDef'> 
45 <HTTP version=" I . !"> 

<URL> http://investor.msn.com/stockquotesjcsp </URL> 
35 <QUERY name="symbor' required="yes'' /> 
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<M-POST> 

<MAN> http:/ywww.upnp.org/service-control/ni-post </MAN> 
<yM-POST> 

<HEADER nanie="Content-Type" value="text/xml" /> 
5 </HTTP> 
</protocol> 

The M-POST and the enclosed MAN elements declare the mandator>' extension 
mechanism to be used. The optional extension mechanism can also be handled in this 
10 way. 

The "HEADER" clement allows the declaration of HTTP headers to be used. 
GENA 

Payload description 

Below is an example of an XML payload description. 

15 <schenia xmlns^^umischema-microsoft-comixml-data" 

xmlns;dt="um:schema-microsoft-com:datatypes"> 

// 

// symbol: a ticker symbol 
20 // 

<ElementTypc name="symbor' dt:type=" string" > 

li 

25 // symbob: airav of "symbol" elements 

// 

<ElementType name="symbols"> 
<element type^"symbol" maxOccurs="*" /> 
30 </ElementType> 

// 

// stockQuote: quote details 

// 

35 

<E]ementType name="stockQtiote'*> 
<element type=="company'' i> 
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35 



<element type="ticker" /> 

<element type="previoui>Cluse" /> 
<element type="openingTrade" /> 
<element type="lastTrade" /> 
<element typc="voiume" /> 
</Eleniciit*rype> 



<ElementType dt:type="string" name="company" /> 
1 0 <ElementType dt:type="striiig" name«"tickcr" /> 

<ElcmcntType dt:type=" string" name="previousClose'* /> 
<ElementType dt:type="string" name='*openingTrade" /> 
20 <ElementType dt:type="string" name="lastTradc" /> 

<ElementType dt:typc="string" namc^'Volume" /> 

15 

// 

// stockQuotes: array of "stockQuole" elements 

// 

25 

20 <ElementType name="stockQuotes"> 

<e!ement name="stockQuote" maxOccurs^"*'* /> 
</Element> 

30 // 

25 // error: error info 

// 

<ElenientType name="error"> 
35 <element type-" reason" /> 

30 <yElementType> 

<ElemenlType dl;type=" string" name="reason" /> 
<yschema> 



Using this declaration, the below are valid XML fragments: 



<symbol> MSFT </symbol> 
45 <symbols> 

40 <symbol> MSFT </syrabol> 

<syfnbol>IBM </s>Tnbol> 
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<symbol> AOL </3ynibo]> 
<symbol> YHOO </symbol> 
<symboi> AMZN </syinboi> 
</symbols> 
5 <stockQuote> 

<conipany>Microsoft%20Corporation</company> 
<tickcr>MSFT</ticker> 

<previousClose>84%20n/l6</previou4iClose> 
<openingTrade>85%20 1 /1 6</openingTrade> 
10 <lastTrade>84%205/1 6</lastTrado 

<volume>2 8 .66%20MiI</volume> 
</stockQuote> 



Messaging patterns 

1 5 The messaging pattern declaration acts as an anchor for puliUig together the 

protocol, delivery characteristics and the payload information. The messaging pattern 
declarations can include these types. 

• Request/response 

• Solicit/response 
20 • One way 

Request/response (RR) . The RR pattern is named. The two samples below arc 
equivalent mechanisms for declaring the protocol to be used for the RR messaging 
pattern. The linking mechanism is useful when multiple RR pairs use the some protocol 
data. This is the case for UPnP. Also, a service may employ multiple protocols for 
25 achieving the same "method" -call. The "is" attribute accepts a list of ID-Refs - 

implying that either of the protocols are equally suitable for accessing the functionality. 

<RequestRespoiise name="getlmage"> 

<protocol> 
30 <HTTP version^" 1 .0-> 

<GET/> 

<URL> http://l 72.30. m.20/fullsizejpB </URL> 

</HTn» 

</protocol> 

35 
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</RequestResponse> 
<protocol id="protoco]Den '*> 
<HTTP version^" 1 .0"> 

<GET;'> 

<URL> http://l 72,30. 1 84.20/fijUsize.jpg <AJRL> 
</HTTP> 
</protocol> 

<RequestResponiie name=''gellniage**> 
<proiocol is="protocoiDefl " l> 

'C'Req uestRcsponse> 

The payloads for request, response and error, in case of XML data, are identified 
by the names of the elements referenced by the "is'* attribute. The schema information 
is assumed to be in the same document. Below are examples using the two schemes: 

<RequestResponse name=''getQuote"> 

// protocol declaration goes here 



<in is='*syTnbor /> 

<out is="stockQuote" f> 
25 <error is=''error" /> 

<.'RequestResponse> 
<RequestResponse name^"getQuote'* 

xmlns: f="http ://electrocommerce.org/finance jcml*' 

xmlns : c = " http: //el ectrocommerce . org/common- xml " 



// protocol declaration goes here 



<in is=''f:symbor t> 
35 <out is="f:stockQuote" /> 

<crror is="c:error" /> 
</RequestResponse> 
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The CDL described herein keeps the element declarations in the "schema" block 
rather than sprinkle them in with the messaging pallem definitions. The reasons for this 
are: 

• Re-use of element declarations is easy. 

• We can re-use fragment validation support as is. 

• Keeping schemas in one place is consistent with the use of in-line schemas 
in S0LI2 and ADO. 

In case the request or response are not XML documents but HTML documents, 
or binary files, the following syntax will be used. The contained element defines the 
nature of the data. The use of MIME is not in the HTTP-specific sense but in the 
"nature of the pay load" sense. The presence of the "is" attributes indicates that the 
MIME type is "text/xml." 

<RequestRcsponsc name="geUmagc''> 



<out> 



<mimc typc="image/jpeg'V> 



<QUV> 

• • * 

</RequestResponse> 
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Delivery characteristics 

The contract may specify the delivery characteristics (sometimes also referred to 
as qtiality of ser\'ice) required or supported by the server. Examples are: 
Ordered, best-effort 
25 • Guaranteed delivery 

Fire-and-foi^et 
Exactly once 
At least once 
Transactional 
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Example 

10 Figures 44-46 depict an exemplary contract for interacting with a stock quote 

Service. 

Figures 47-50 depict an XML schema for defining Contracts. 
5 Having described and illustrated the principles of our invention with reference to 

IS 

an illustrated embodiment, it will be recognized that the illustrated embodiment can be 
modified in arrangement and detail without departing firom such principles. Il should be 
understood that the programs, processes, or methods described herein are not related or 
2Q limited to any particular type of computer apparatus, unless indicated otherwise. 

10 Various types of general purpose or specialized computer apparatus may be used with 
or perform operations in accordance with the teachings described herein. Elements of 
the illustrated embodiment shown in software may be implemented in hardware and 
vice versa. 

In view of the many possible embodiments to which the principles of our 
1 5 invention may be applied, it should be recognized that the detailed embodiments are 
illustrative only and should not be taken as limiting the scope of our invention. Rather, 
we claim as our invention all such embodiments as may come within the scope and 
spirit of the following claims and equivalents thereto. 
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We claim: 

1 . A computing device providing a user control point for with connectivity 
to at least one controlled device via a networking medium, the computing device 
5 comprising; 

a controlled device description document having a service control protocol 
declaration for at least one service provided by the at least one controlled device; and 

a general programming interfece-to-network messaging adapter operating based 
on the controlled device description document to provide a programming interface to 
10 application programs running on the computing device, and to convert calls to the 
programming interface into networking messages according to a service control 
protocol defined per the controlled device description document, and to issue the 
networking messages via the networking medium Co the coatrolled device to invoke 
commands of the at least one service. 

15 

2. The computing device of claim 1 wherein the programming interface is 
an object integration interface according to an object-oriented programming model. 
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FIG. 5 
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FIG. 15 

^<device> 

<iconList> 
<icon> 

<sire>16</si2e> 
<color>0</color> 
<deplh> 8</d e pth > 
<imageType>PNG</imag©Type> 

<image>"http:/ydevice.local/iconpath/icon 1 6bw. png"</image> 
</icon> 
<icon> 

<size>32</size> 

<color>0</color> 

<depth>8</depth> 

< jmageType>P NG<AimageType> 

<image>"http;y/deviceJocal/iconpatri/tcon32bw.png'*</image> 
</icx>n> 
<icon> 

<size>48</size> 

< color>0 </co k5r> 

< depth> B-^/depth > 

< imageTy pe> P N G</i ma g eTy pe> 

<rmage>"http://device.local/iconpath/icon48bw. png" </image> 
</icon> 
<icon> 

<size>15</size> 

<cotor>1 </ca\or> 

<depth>8</depth> 

<imageType>PNG</imageType> 

«irnage>*'http://device.local/iconpath/icon16c.png"«:/image> 
</icon><devioe> 
<icon> 

<size>32</si2e> 

<color>0</color> 

<depth>B</depth> 

<tmageTy p)e > P N G </i mag eTy pe> 

«:tmage>"http://device.localAiconpath/icon32c.png"</image> 
</ioon> 
<icon> 

<size>48</si2e> 

<color>0</color> 

<depth> 8</deptb> 

<imageType> P NG </im3g eTy pe> 

<image>"http://devtce.local/iconpath/icon48c.png"</image> 
</icon> 

</iconLjst> 

> » a 

\^</device> 
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/ 



<?xml versions" 1.0"?> 
<scpd xnnlns-'x-schenna:scpdt-schema.xmr' 
<service StateTable> 
<stateVariable> 

<name>currentChannel</name> 
<d ataTy pe> n u m ber</d ataType> 
<allowedValueRang8> 
<minimum>0</minimum> 
< maxim um> 5 5 </m axim um > 
<step>1</step> 
</aHowed VaiueRan ge> 
</stateVariable> 
</serviceStateTab!e> 



<actionList> 
<action> 

<name>ChannelUp</name> 
</action> 

<action> 

<name>ChannelDown</name> 
</action> 

<action> 

<name>SetChannel</name> 
<argument> 

<name>newChannel</name> 
<reiatedStateVariable> 
currentChannel 
</relatedStateVariable> 
</argument> 
</action> 
</actionUst> 
</scpd> 
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/ 

<contract> 
<protocol id- "protocolDef > 
<HTTP version="1.1"> 
<URL></URL> 
<IV!-POST> 

<MAN>http://www.rnicrosoft.conn/protocols/ext/XOAP</MAN> 
</M-POST> 

<HEADER namee"Content-Type" vahje="texVxmr /> 
<1- Need to put in extension headers here — > 
</HTTP> 



</protcx;ol> 

<RequestResponse name- 'que ryStateVariable''^ 
<protocol is^^protocolDer* 
<in is="queryStateVariable"> 
<out is=''queryStateVanaWeResponse"> 
< error is-'quefyStateVariableResponse''> 

</RequestResponse> 

<RequestResponse name="invokeActian"> 

<protocol is=''protocolDer> 

<jn js="SerializedStream"> 

<out is="invokeActionResponse"> 

<error is="invokeActionResponse"> 
</RequeslResponse> 



<Schema name="upnp_scpdr 
xmJ ns= "u rn : schemas-m ic rosoft-com; xml-d ata" 
xmins:dt="urn:schemas-microsoft-com:datatypes"> 

<!- Common — > 

<ElementType narT>e="_retum" content="textOnly* dtitype- 'string" t> 
<EIementType name="_fault" content='textOnIy" dttype="string" /> 

<!- Query State Variable Call -> 

<ElementType name='VariableNanne" content="textOnly" dl:type="stnng" /> 

<ElementType name="queryStateVariable'* content="eltOnty" model="closed"> 

< element type="variableName" /> 
</BementType> 

<t- Query State Variable Response -> 

\ 
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/ 



<ElementType name="queryStateVariabIeResponse" content="eltOnly" 
model="closed"> 

<group order=''one"> 

<element type="_return"> 
<element type="_faulf' > 
</group> 
</ElementType> 

<!- Invoke Action Call — > 

<AttributeType name="main" dt:type="idrer /> 
<AttributeType name=" headers" dtrtypes^idref /> 
<AttributeType name="id" dt;type="id" /> 

<ElementType name="sequenceNumber" content="textOnly" dt:type="inr> 
<AttrbuteType name="dt" dttype="string" dt:values="int'' /> 

ottribute type="dr /> 
</ElementType> 

<ElementTypename="headers" content="e!tOnly*' model="closed" 

<attribute type="id" required="yes" /> 

<element type="sequenceNumber" /> 
</ElementType> 

<E!ementType name="actionName" content='*textOniy'* dt:type="string" /> 
<EiementType name="actionArg" content="textOnly" dt:type="string'* /> 

<ElementType name="invokeAction" content-'eltOnly" model=*'closed"> 
ottribute type="id'' required="yes" /> 

<element type- 'ac:tionName"> 

<elennent type="actionArg" nninOccurs="0" maxOccurs="*"> 
</ElementType> 
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/ 

<ElementType name- 'SerializedStream" content=''eltOnly" modeI="closed"> 
<attribute type="main" requirecl="yes" /> 
<attribute type-' headers" required="yes" /> 

<e!ement type="headers"> 
<element type- '(nvokeAction"> 

</EiementType> 

<!— Invoke Action Response — > 

<ElementType name="(nvokeAction Response" content="eltOnly" mode!="cIosed" 
<group ordef="one"> 

<element type=*_retum"> 
< element type="_fautt"> 
</group> 
</BementType> 
</Schema> 
</contract> 
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<?xml version="1.0"?> 
<Schema name- 'upnp_scpdr 

xmlns="urn:schemas-microsoft-com:xmi-clata" 

xmlns:dt="urn:schema3-microsoft-com:datatypes"> 

<!- Common Elements and Attributes --> 

<EIementType name=*'name" content="textOnly" dtrtype- 'string" /> 
<!- Service State Table -> 

<ElementType name=''minimum" content-'textOnly" dttype-'number" /> 
<ElementType name="maximum" content=''textOnly" dt:type="number" /> 
<ElementType name="step" content="textOnly" dtitype-'number** /> 

<ElementType name="aliowedValue Range" content="e!tOnly" model="dosed"> 

^element type="minimum" /> 

<element type="maximum" /> 

<element type- 'step" minOccurs="0" /> 
</ElementType> 

<ElementType name="allowedValue" content="textOnly'* /> 

<ElementType name="allowedValueList" content- *eltOnly" model="closed"> 

<element type='*allowedValue" minOccurs="1" maxOccurss"*" /> 
</El9mentType> 

<ElementType name="dataType*' content="textOnly" dt:type='*string" /> 

<EIementType name="stateVariable" content="eltOnly" model="closed"> 
<€lement type- 'name" /> 
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/ 

<element type- 'data Type" /> 

<group minOccurs=''0" maxOccurs-'1" order="one"> 

<elennent type="aliowedValueRange" /> 

<element type="aliowedValueUst" /> 
</group> 
</ElementType> 

<ElementType name=''deviceStateTable" content="eltOnly" model ="ciosed"> 

<e!ement type="5tateN/ariable" minOccurs="1" maxOccurs="*" /> 
</ElementType> 



<!— Action List -> 

<EIementType name=''relatedStateVariable" content=''textOnly" dt:type="string" / 

<ElementType name="argument" content="eltOnly" model="ciosed"> 

<element type-'name" /> 

<element type="related State Variable" /> 
</ElementType> 

<ElementType name="action" content="eltOnly'' model="c!osed"> 
<element type="name" /> 

<element type="argument" minOccurs="0" max0ccur5="**' /> 
</EiementType> 

<ElementType narne="actionUsr content="eltOnly" model="closed"> 

<e lament type- 'action" minOccurs="0" maxOccur5="*" >> 
</ElementType> 

<!- Root Element -> 

<ElementType name="dcpd" content="eltOnly" model="closed"> 

<element type="deviceStateTable" /> 

<element type="actionUst'* /> 
</ElementType> 
</Schema> 
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I 

object, 

uuid(<foo>), 

dual. 

helpslringClUPNPDevice interface"). 

pointer_defaun(unique) 

1 

interface lUPNPOevice : IDispatch 

{ 

[prc^get id (DISPID_UPNPDEVICE_DESCRIPT10N DOCUMENT). 
hetpstrtngCretums the document from which the properties of this device are 
being read")] 

H RESULT Description Document([restricted. hidden, out, retval] 
lUPNPDescriptionDocument *' ppudd Document): 

purpose: returns the document from which the properties of this device are 
being read. 

parameters: ppudd Document, A reference to the description document 
object from which data about the device is being read. This must be freed when no 
longer needed. 

return values: S_OK. ppuddDocument is a referrK:e to the device's 
description document. 

[propget, id(DISPID. UPNPDEVICEJSROOTDEVICE), 

helpstring ("denotes whether the physical location infomnation of this device can 
be ser*)] 

HRESULT lsRootDevice([out, retvalj VARIANT_BOOL * pvarb); 

parameters: pvarb. the address of a VARlANT_BOOL that will receive the 
value of VARIANT_TRUE if the current device is the topmost device in the device 
tree, and will receive the value of VARIA^^^_FALSE otherwise, 
return values: S_OK, varb Is set to the appropriate value 
note: if a device is a root device, calls RootDevice() or ParentDevice() will 
return NULL 



(propget. id(DISPlD_UPNPDEVICE_ROOT). 
helpstringC'netums the top device in the device tree")] 
HRESULT RootDevice([out. reNal] lUPNPDevice " ppudDeviceRoot): 
purpose: returns the top device in the device tree 
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parameters: ppudDeviceRoot. On return, this refers to the "roof device of 
the current device tree. The root device is the topmost parent of the current device. 
If the current device is the root device this method will set ^ppudDeviceRoot to null, 
and return S_FALSE. 

return values: S_OK, ^ppudDeviceRoot contains a reference to the root 
device. S_FALSE, the current device is the root device. *ppudDevjceRook is null. 

[propget. id(DISPID_UPNPDEVICE_PARENT). 
helpstring("returns the parent of the current device'*)] 
HRESULT ParantDevice([out, retvaQ lUPNPDevice ** ppudDeviceParent); 

parameters: ppudDeviceParent, On retum. rf the device has a parent this is 

the address of a lUPNPDevice object which can describe the parent This must be 

released when no longer needed. If the device has no parent (it is a "roof device), 

than this value will be set to null. 

return values: S_OK, ppudDeviceParent contains a reference to the device's 

parent. S_FALSE, the current device is the root device, which has no parent 

"ppudDeviceRoot is null. 

[propget, id(DISPID_UPNPDEVICE_CHILDREN). 
helpstringCretums a collection of the children of the current device")] 
HRESULT Children([out retval] lUPNPDevices ** ppudChildren); 

parameters: ppudChitdren, On retum, this is the address of a newly-created 
lUPNPDevices collection that can enumerate thisjdevice's children. This must be 
released when no longer needed. If the device has no children, this method will 
retum a collection ot>ject with a length of zero. 

retum values: S_OK, ppudChildren contains a list of the device's children. 

[propget id{DISPID_UPNPDEVICE_UDN). 
helpstringCretums the UDN of the device")] 
HRESULT UniqueDeviceName([out. retval] BSTR * pbstrUDN); 

parameters: pbstrUDN, On return, this contains the address of a newly- 
allocated string which contains the device's Unique Device Name (UDN). The UDN 
is globally unique across all devices - no two devices will ever have the same UDN. 
This value must be freed when no longer needed. 

retum values: S_OK pbstrUDN contains the UDN of the device 

• * » 
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[propget. id(D!SPID_UPNPDEVICE_DISPLAYNAME). 

helpstringfretums the (optional) display name of the device")] 
HRESULT DisplayName([out, retval) BSTR * pbstrDisplayName); 

parameters: pbstrDisplayName, On return, this contains the address of the 
device's display name. This value must be freed when no longer needed. If the 
device does not specify a display name, this parameter will be set to null. 

return values: S_OK, bstrOisplayName contains the display name of the 
device. pbstrDisplayName must be freed. S_FALSE. the device did not specify a 
display name. ^pbstrDisplayName is set to null. 

note: it is possible for multiple devices to have the same display name. 
Applications should use UniqueDeviceName() to determine if two device objects 
refer to the same device. 

[propget, id(DlSPID_UPNPDEVICE_CANSETDISPLAYNAME). 
helpstringC'denotes whether the physical location information of this device can 
be set")] 

HRESULT CanSetDisplayName([out, retval] VARIANT_BOOL * pvarb); 

param^ers: pvarb, the address of a VARIANT_BOOL. This is true (1=0) on 
return when the device's display name can be set (via SetDisplayName) 
return values: S_OK varb is set to the appropriate value 

[id(DISPID_UPNPDEVICE_SETDISPLAYNAME). 
helpstringC'sets the display name on the device'*)] 
HRESULT SetDlsplayName([in] BSTR bstrOisplayName): 

parameters: bstrOisplayName, the value to set the device's display name to. 
return values: S_OK, varb is set to the appropriate value, 
note: On success, this method sets the display name used by a device. 
Note that this method changes the display name on the device itself, not simply on 
the local object. This will block while the name is being set. 
Additionally, this change will be made on the device alone, and will not be reflected 
in the current device object. After a successful call to this method, DisplayName 
will continue to return the 'old' value). To read the device's current name, the caller 
must re-load the device's description. 

[propget. id(DISPID_UPNPDEVICE_DEVICETYPE), 
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helpstringCretums the device type URl")] 

HRESULT Type([oiit. retvall BSTR * pbstrType); 

parameters: pbstrType. On return, this contains the address of a r>ewty-aUo€ated 
string containing the device's type URI. This value must be freed when no longer 
needed. 

return values: S_OK, bstrType contains the type URI of the device, and must be 
freed when no longer needed. 

Ipropget. ld(DISPlD_UPNPDEVICE_SERVlCES). 
helpstrtngrratums the collection of services exposed by the device**)] 
HRESULT Services([out, retvalj lUPNPServioes " ppusServices); 

parameters: ppusServices. On return, this is the address of a r^wly-created 
lUPNPServices collection that can enumerate the services exposed by the device. 
This must be released wtien no longer needed. If the device exposes no services; this 
method will return a collection object with a length of zero. 

return values: S_OK, pusServices contains a list of the device's children. 

[propget. id(DISPID_UPNPDEVlCE_SERVlCEIDENTIRER). 
helpstrlngC'returns the (optional) service identifier of the device")] 
HRESULT Service ldentifier(fout, retval] BSTR • pbstrSenricelD ); 

parameters: pbstrServicelD, On return, this contains the address of a newly- 
allocated string containing the contents of the device's Serviceldenlifier element, iif the 
- device specifies one. This value must be freed when no longer needed. If the device 
does not specify a Serviceldentifier value, this pararrieter will be set to null. 

return value: S_OK. bstrServicelD contains the service identifier of the device. 
pbstrServicelO must be freed. S_FALSE, the device did not specify a service identifier. 
*pbstrServicelD is set to null. 

note having a Serviceldentifier is mutually exclusive with having services. Any 
device wilt either have a list of services or a Serviceldentrfter, but not both. 

[id(DISPID_UPNPDEVICEDESCRIPT10N_L0ADSMALLIC0N). 
helpstringCloads a small (litlebar-sized) icon representing the device, encoded in the 
specified fbnmat")] 

HRESULT ljoadSmalllcon([tn] BSTR bstrEncodingFormat. 
[out. reWal] BSTR * pt>3trtconURL); 
parameters: 
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bstrEncodingFormat. A string containing the minne-type representing the desired 
encoding fornriatof the icon. pbstrlconURL, On return, *pbstrlconURL contains a 
newly-allocated string representing the URL from which the icon can be loaded. 
This string must be freed when no longer needed. 

return values: S_OK, *pbstriconURL contains a reference to an icon, 
encoded in the desired encoding format 

[id(DISPID_UPNPDEVICEDESCRIFT10N_L0ADIC0N). 
helpstringC'loads a standard-sized icon representing the device, encoded in the 
specified format")] 

HRESULT Loadicon([in) BSTR bstrEncodingFormat, 
[out, retval] BSTR * pbstrlconURL); 

parameters: bstrEncodingPomnat, A string containing the mime-type 
representing the desired encoding format of the icon. pbstrlconURL, On return, 
•pbstrlconURL contains a newly-allocated string representing the URL from which 
the icon can be loaded. This string must be freed when no longer needed. 

return values: S_OK, *pbstrlconURL contains a reference to an icon, 
encoded in the desired encoding format 

[propget, td(DISPlD_UPNPDEVICEDESCRIPT10N_PRESENTATI0NURL). 
helpstring("obtains a presentation URL to a web page that can control the 
device")] 

HRESULT PresentationURL([out, retvalj BSTR * pbstrURL); 

parameters: pbstrURL, on retum, the address of a newty-al located string 
containing the web-page-based control URL If the device did not specify a 
presentation URL, an empy string ("") will be returned. 

retum values:S_OK, bstrURL contains a newly-allocated URL that must be 
freed when no longer needed. S_FALSE, the device does not have a presentation 
URL. pbstrURL is set to null. 

[propget. id(DISPID_UPNPDEViCEDESCRIPTION_PHYSlCALLOCATION), 
heipstringC'a set of properties describing the device's physical location")] 
HRESULT PhysicalLocation([out, retval] lUPNPPropertyBag * pupl); 
parameters: pupl on return, the address of a newly-allocated 
UPNPPropertySag object which contains infomnation about the device's physical 
location 

return values 
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S_OK upi contains a newly-allocated object that the caller must free when it 
is no longer needed. 

note: if the object does not provide any description information, an empy 
property bag will be returned. See SelPhysicalLocation for a listing of defined 
values in a physical location property bag. 

(propget 

id(DISPID_UPNPDEVICEDESCRIPTION_CANSETPHYSICALLOCATION). 

helpstringf denotes whether the physical location information of this device can 
be set")] 

HRESULT CanSetPhysicalLocation([out, retval] VARIANT_BOOL * pvarb); 

parameters: pvarb the address of a \/ARIANT_BOOL. This is tnje (!=0) on 
return when the device's physical location can be set (via SetPhysical Location) 
return values: S_OK varb is set to the appropriate value 

[id(DISPID_UPNPDEVICEDESCRIPTION_SETPHYSICALLOCATION). 
helpstring("writes a set of properties describing the device's physical location to 
the device")) 

HRESULT SetPhysicalLocation([inl lUPNPPropertyBag * pupl); 

parameters: pupl A UPNPPropertyBag object which contains the name- 
value pairs representing the device's current location, the function will not free the 
object. 

retum values: S_OK he device has been updated with the supplied 
physical location information 

note: the following are standard values in the physical location property bag: 
country, campus, building, floor, wing. room, latitude, longitude, altitude. These 
values can be used programmaticalty to implement sorting or filtering functionality 
based on the device's location. Additionally the property bag supports the following 
value: description, which contains a user-displayable string representing a device's 
location which does not have programattic significance. Additionally, the physical 
location update will be made on the device alone, and will not be reflected in the 
current device object. After a successful call to this method. PhysicalLocation will 
continue to retum the 'old' value. To read the device's current name, the caller 
must re-load the device's description. 
} 
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[propget id(DISPID_UPNPDEVICEDESCRIPTION„PRODUCTNAME), 
helpstringf'a displayable string containing the product name")] 
HRESULT ProductNamedout, retval] BSTR * pbstr); 

parameters: pbstr on return, the address of a newly-allocated string 
containing the product name of the device. 

return values: S_OK pbstr contains a newly-allocated string that must 
be freed when no longer needed. 

[propget, id(DISPlD_UPNPDEVICEDESCRIPTION_DESCRIPTION). 
helpstringC'displayable summary of the device's function")] 
HRESULT Description([out, retval] BSTR * pbstr): 

parameters: pbstr on return, the address of a newly-allocated string 
containing a short description of the device meaningful to the user. 

return values: S_OK pbstr contains a newly-allocated string that must 
be freed when no longer needed. 

[propget. id(DISPID_UPNPDEVICEDESCRIPTION_M0DELN(AME). 
helpstringC'displayable model name")] 
HRESULT ModelName([out. retval] BSTR * pbstr); 

parameters: pbstr on return, the address of a newty-allocated string 
containing the manufactuer's model name of the device. 

return values; S_OK pbstr contains a newly-allocated string that must 
be freed when no longer needed. 

[propget, id{DISPID_UPNPDEVICEDESCRIPTION_SERIALNUMBER), 
helpstringC'displayable serial number")] 
HRESULT SerialNumber([out, retval] BSTR * pbstr): 

parameters: pbstr on return, the address of a newly-allocated string 
containing the manufacturer's serial number of the device. 

return values; S_OK pbstr contains a newly-allocated string that must 
be freed when no longer needed. 

note: a device's serial number is not guaranteed to be globally unique. The 
DeviceUniqueName should atv/ays be used to distinguish devices. 

[propget. id(DISPID_UPNPDEVICEDESCRIPT10N_MANUFACTURERNAME). 
helpstringC'displayable manufacturer name")] 
HRESULT ManufacturerName([out. retval] BSTR * pbstr); 
parameters 
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pbstr, on return, the address of a newly-allocated string containing the name of the 
device's manufactuer. 

return values; S_OK, pbstr contains a newly-allocated string that must be 
freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_MANUFACTURERURL). 
heipstringC'URL to the manufacturer's website")] 
HRESULT ManufacturerURL((out. retval] BSTR * pbstr); 

parameters: pbstr, on return, the address of a newly-allocated string 
containing the URL of the manufacturer's website. 

return values: S_OK, pbstr contains a newly-allocated string that must be 
freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_M0DELNAME), 
helpstringC'displayable model name")] 
HRESULT ModelName([out. retval] BSTR * pbstr); 

parameters: pbstr, on return, the address of a newly-allocated string 
containing the manufactuer's model name for the device. 

return values: S_OK, pbstr contains a newly-allocated string that must t>e 
freed when no longer needed. 

[propget. id(DISPID_UPNPDEViCEDESCRIPTION_SUPPORTLIST). 
helpstring{"technlcal support contact information")] 
HRESULT SupportLlst([out retval] BSTR • pbstr); 

parameters: pbstr. on return, the address of a newly-allocated, multi-line 
string containing phone numbers and other information that can guide the user to 
technical support. This string must be freed when no longer needed. 

return values: S_OK, pbstr contains a newly-allocated string that must be 
freed when no longer needed. 

[propget, id(DISPID_UPNPDEVICEDESCRIPTION_FAQLIST), 
helpstringC'FAQ access display information")] 
HRESULT FAQList((out, retval] BSTR * pbstr); 

parameters: pbstr, on return, the address of a newly-allocated, multi-line 
string containing FAQ information that can provide the user with URLs at which 
device FAQs may be located. 

retum values: S_OK. pbstr contains a newly-allocated string that must be 
freed when no longer needed. 
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[propget. id(DISPID_UPNPDEVICEDESCRIPTION_UPDATEUST), 

helpstring ("information explaining where the user can update the device's 
firmware")] 

HRESULT UpdateList([out, retval] BSTR * pbstr); 

parameters: pbstr. on return, the address of a newiy-ailocated, multi-line 
string containing information and URLs from which the user can download updates 
for the device's firmware. 

return values: S_OK, pbstr contains a newly-allocated string that must be 
freed when no longer needed. 
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[ 

object, 

uuid(FDBC0C73-BDA3-4C66-AC4F-F2D96FDAD68C). 
dual, 

helpstringC'lUPNPDevices Interface"), 
pointer_default(unique) 

] 

t UPNPP rope rty Bag 
{ 

[propget. id(DISPID_UPNP_PROPERTYBAG_READ). 
helpstringC'reads a value from the property bag")] 

HRESULT Read([inl BSTR bstrName, [out, retval] VARIANT * pvarResult); 
parameters: bstrName, name of the property to read, case is ignored. 
pvarResultvalue of the property, if the property doese not exist, this is of type 
VT_EMPTY 

retum values: S_OK, the value was found in the property bag, and returned 
in pvarResult. S_FALSE, there was no value with the given name in the property 
bag. *pvarResuIt is of type VT_EMPTY 

Ipropget, id(DISPID_UPNP_PROPERTYBAG_WRITE), 
helpstringC*writes a value to the property bag")] 
HRESULT Write([in] BSTR bstrName. [in] VARIANT * pvarValue); 

parameters; bstrName, name of the property to write, case is preserved 
when writing. The supplied value will replace any other values of the same name, 
even if they differ in case. pvarValue, value of the property to write. 

return values: S_OK, the value was written to the property bag, replacing the 
value currently associated with this property, if it existed. 

[propget ld(DISPID_UPNP_PROPERTYBAG_DELETE). 
helpstringC'removes a value from the property bag")] 
HRESULT Delete([inl BSTR bstrName); 

parameters: bstrName. name of the value to remove from the property gab. 
case is ignored when finding a value to remove. 

retum values: S_OK, the value has been removed from the property bag. 
S_FALSE, the value was not found in the property bag. 

}: 
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[ 

object, 

LJuid(A295019C-DC65-47DD-90DC-7FE918A1AB44). 
dual, 

helpstringC'lUPNPService Interface"), 

pointer_default(unique) 

1 

interface J UP NP Service ; IDispatch 
{ 

[id(1), helpstringfrnethod GetProperty")] 
HRESULT GetProperty( 
[in) BSTR bstrPropertyName, 
[out, retval] VARIANT *pValue 

): 

[id(2), helpstringfmethod InvokeAction")] 
HRESULT lnvokeAction( 
[in] BSTR bstrActionName, 
[in] VARIANT saActionArgs. 
[out, retval] long *plStatus 

); 

[propget. id(3), helpstring("property DCP!")] 

HRESULT DCPI( 

[out, retval] BSTR 'pVal 

): 

(propget id(4), 

helpstringC'returns a manufactuer-defined extension property")] 
HRESULT VendorB<tension([out, retval] VARIANT * pvarValue ); 

parameters: pvarValueOn return, this variant is filled with the value of the 
"extension" element. If none exists, pvarValue is set to VT_EMPTY 

return values: S_OK, varValue is set to the extension element. S_FALSE, 
no vendor extension element exists. pvarValue is VT__EMPTY 
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[ 

object, 

uuid{FDBC0C73-BDA3-4C66-AC4F-F2D96FDAD68C). 
dual, 

helpstringC'tUPNPDevices Interface"), 
pointer_default(unique) 

] 

interface lUPNPDevices : IDispatch 

{ 

[propget, id(1), helpstring("property Count"*)] 
HRESULT Count( 
[out. retval] long *pVal 

): 

[propget. id(DlSPlD_NEWENUM), helpstring ("property _NewEnum")] 

HRESULT _NewEnum( 

[out retval] LPUNKNOWN *pVal 

); 

[propget. id(DISPID_VALUE). helpstring("property Item")] 

HRESULT ltenn( 

[in] long lindex, 

[out. retval] VARIANT *pVal 

): 
}; 
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FIG. 43 

[ 

object, 

uuid(3F8C8E9E-9A7A-4DC8-BC41-FF31FA374956), 
dual, 

helpstringriUPNPServices Interface"), 
pointer_defautt(unique) 

1 

interface lUPNPServices : IDispatch 
{ 

[propgel, id(1), helpstring('*property Count")] 
HRESULT Count( 
(out, retval] long *pVal 

): 

[propget, id(DISPID_NEWENUM). helpstringC'property _NewEnum'')] 

HRESULT _NewEnum( 

[out, retval] LPUNKNOWN *pVa! 

); 

[propget. id (DISPI DEVALUE), helpstringfproperty Item")] 
HRESULT ltem( 
[in] long Itndex. 
[out, retval] VARIANT "pVal 
): 
}: 
*\ 
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FIG. 44 

/ 

<contract> 

<protocol id="protocolDef' > 
< HTTP versions" 1.r*> 
<URL> http://investor.msn.conn/stockquote </URL> 
<M-POST> 

<MAN> http://www.upnp,org/service-control/m-post </MAN> 
<M-POST> 

<HEADER name="Content-Type" value="text/xnnl" /> 
</HTTP> 
</protocol> 

<RequestResponse name="getQuote"> 

<protocQl is="protocolDer t> 

<in is- 'symt>cr /> 

<out is=*'stockQuote" /> 

<error is="error" /> 
</RequestResponse> 

<RequestResponse nanne=''getQuotes"> 

<protocol is="protocolDef' /> 

<in is="symbols" /> 

<out is="stockQuotes" /> 

<error is="error" /> 
</RequestResponse> 

<!— // schema definition follows —> 

<5chema xnrtlns="um:schenna-microsoft-conn:xml-data" 
xmlns:dt="um: schema-m icrosoft-conn :d atatypes**> 

<ElennentType name="symbor dt:type="string" t> 

<ElementType nanr»e-'symbols*'> 

<element type="symbor maxOccurs='**" /> 
</ElementType> 

<ElementType name="stockQuote"> 
<e!ement type-'company" /> 
<element type="ticker" /> 



\ 
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FIG. 45 

/ 

<elemen1 type=''previousClose" t> 
<element type- 'openingTrade" /> 
<element type="IastTrade" /> 
<elBment type -Volume" /> 
</ElementType> 

<ElementType dt:type='*string" name=" company" /> 
<ElementType dt:type="string" name="ticker'* /> 
<ElementType dt:type="string" name=*'previousClose" /> 
<ElernentType dt:type="string" name="openingTrade" l> 
<ElementType dt:type= "string" name- 'lastTrade" /> 
<ElementType dt:type="string" name=*Volume" /> 

<ElementType name-*stockQuotes"> 

<element name="stockQuote" maxOccurs="*" l> 
</Element> 

<ElementType name="error"> 

<element type-'reason" /> 
</BementType> 

<EIementType dt:type="string" name="reason" /> 
</schema> 
</contract> 

Request for "getQuote" 

M-POST /stockquoles HTTP/1,1 
Host: amarg5:8586 
Content-Type: text/xml 

Man: **http://www.upnp,org/service-control/m-post*; ns=01 
01 -Method Name: getQuotes 
01-MessageType: Call 
Acxept-Language: en-gb, en;q=0.8 

Referer: http://amarg5yuPnPService/Services/Stock/C!ient/ticker.htm 
Content-Length: 327 

User-Agent: Mozillay4.0 (compatible; MSIE 5.01; Windows NT 5.0) 
Connection: Keep-Alive 
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FIG. 46 

<symbol>MSFT</synnbol> 
Response for "getQuote" 

HTTP/1.1 200 OK 

Connection: dose 

Cache-Control: private 

Date: Men Aug 16 15:37:35 PDT 1999 

Expires: Mon Aug 16 15:37:35 PDT 1999 

Content-Type: text/xml 

Content-Length: 7912 

Man: "http://www,upnp.orgyservice-control/m-posl"; ns=01 
Ext 

01-MessageType: CallResponse 

<stockQuote> 
<company>Microsoft%20Corporation</connpany> 
<ticker>MSFT</ticker> 

<previousClose>84%2011/16</previousClose> 
<openingTrade>85%201 /1 6</openingTrade> 
<lastTrade>84%205/1 6</lastTrade> 
<volume>28.66%20Mil<A/olume> 
</stockQuote> 
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FIG. 47 

/ 



<!" XDR Schema for protocol section of contract -> 

<schema name- 'contracf* 

xmlnss^umrschema-microsoft-comixml-data** 
xmlns:dt="um :schema-microsoft-com:d atatypes"> 

<EIementType name- 'contract" 

xmlns: protoooIN S="contract-protocot- 
xmlns:^nsgPattemNS="contract-msgPattems" 
xmlns:schennaNS-'um:schema-microsoft-com:xml-data"> 

<element type=**protocolNS: protocol" /> 

<e!ennent type-"msgPattemNS;RequestResponse" minOccurs=-0" 
maxOccurs="**' /> 

<element type*"msg Pattern NS:SollcURe5ponse" mlnOccurs="0" maxOccurs- 

/> 

<element type='*schemaNS:schema" nninOccurs="0" nnaxOccurs- /> 

</ElementType> 
</schema> 
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FIG. 48 
/ 



Protocol o 
<!- XDR Schema for protocol section of contract — > 

<schema name='*con tract-protocol" 

xmlns="urn:schema-microsoft-com:xml-data'' 
xmlns: dl="u m :sch ema-m icrosoft-com :datatypes"> 

<ElementType name="protocor> 

<!-- ID -> 

<AttributeType name="ld'* dttype="id* l> 
<Attribute type="id" t> 

<group order="one"> 
<element xmlns: http="contract-protocomTTP" type="http:HTTP" /> 
<element xmlns:gena="contract-protocol-GENA" type=s"gena:GENA" l> 
II other protocol definitions go here 

</group> 

<yElementType> 
</schema> 
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FIG. 49 



HTTP 

<!" XDR Schema for HTTP section of contract -> 

<schema name="contract-protocol-HTTP*' 

xmlns="um:schema-microsoft-com:xml-data** 
xmlns;clt="urn:schema-microsoft-com:datatypes"> 

<ElennentType name=''HTTP"> 
<!- HTTP version -> 

<AttributeType name='VERSION" dt:type="string" default="ri" /> 
<Attribute type='VERSION" /> 

<!— The Verb to use —> 
<group order="one"> 

<element type=-GET' /> 

<element tvT3e=''POST" /> 

<element type=''M-POST'' A> 
</group> 

<!- The protocol data -> 

<element ty pe="U RL" /> 

<element type^^^'QUERY*' minOccurs="0" /> 

<element type="HEADER" minOccurs=!*'0'* /> 

</ElementType> 

<ElementType name="URL'' dt:type="string" l> 

<ElementType nanne="QUERr'> ^ 

<attribute type="name" /> 

<attribute type="vatue" /> 

<attribute type- 'required" /> 
</ElementType> 



\ 
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FIG.50 



<ElementType name="HEADER"> 

<attribute type="name" /> 

<attribute type="vaiue" required='Ves" l> 
</ElementType> 

<!-- Verb declarations -> 
<ElementTyp8 name- 'GET'7> 

<EtementType nanne="POST'> 

<element type="PARAM'* minOccurs='*0" maxOccurs="*'' /> 
</ElementType> 

<ElementType name="PARAM"> 

<element type="nanne" /> 

<element type='*defaulf* /> 

<element type='Value" /> 

<element type="required" /> 
</ElementType> 

<AttributeType name="name'* dt:type="string" requireds'Ves" /> 
<AttributeType name="defauir dt:type="string" /> 
<AttributeType name^'Value" dt:type="string" /> 
<AttributeType name-'required" dt:type="boolean" default="no" /> 

<ElennentTyp8 name="M-POST"> 

<elennent type="MAN" /> 
</ElennentType> 

<EIementType nanfie="MAN" dt:type="string" /> 
</schema> 
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AMENDED CLAIMS 
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1 . . A computing device providing a user control point with connectivity 
to at least one controlled device via a networking medium, the computing device 
comprising: 

a controlled device description document having a service control protocol 
5 declaration for at least one service provided by the at least one controlled device; 
and 

a general programming interface-to-network messaging adapter operating 
based on the controlled device description document to provide a programming 
interface to application programs running on the computing device, and to convert 
1 0 calls to the programming interface into networking messages according to a seivice 
control protocol defined per the controlled device description document, and to issue 
the networking messages via the networking medium to the controlled device to 
invoke commands of the at least one service. 

25 2.. The computing device of claim 1 wherein the programming interface 

is an object integration interface according to an object-oriented programming 
model. 

3. A method for a client program on a first computing device to 
20 programmatically control a service of a logical device reaUzed on a remote 

computing device on a data communications network via peer-to-peer networking 
connectivity from the first computing device on the data communications network. 

the method comprising: 

obtaining a description document via peer-to-peer networking from the 
25 remote computing device, the description document defining a service-specific 
protocol involving an exchange of data messages via pecr-to-pcer networking 
connectivity with the remote computing device for controlling the logical device 

service on the remote computing device; 

based on the description document, dynamically generating an instance of a 
30 programmatic interfece for invocation by the client program to initiate service- 
specific operations for remote control of the logical device service; 
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on invocation of the method members by the client program, translating the 
client program's programmatic interface invocation into the exchange of data 
messages via peer-to-peer networking connectivity in accordance with the 
description document for effecting control of the logical device service. 

4. The method of claim 3 wherein the programmatic interface is an 
object integration interface of an object-oriented programming model. 

5. The method of claim 3 wherein the data messages are in a mark-up 
language and exchanged via a hypertext transport protocol. 

6. The method of claim 3 wherein the service-specific operations 
include invoking commands of the service, querying a state of the service, and 
receiving and responding to events of the service. 

7. The method of claim 3 wherein the service has a set of properties 
defining a state of the service, and the service-specific operations include querying 
and setting values of the set of properties. 

8. A computer-readable medium carrying computer-executable software 
program code thereon for executing on a first computing device on a data 
communications network to perform a method for a client program on the first 
computing device to programihatically control a service of a logical device realized 
on a remote computing device on a data communications network via peer-to-peer 
networking connectivity firom the first computing device on the data 
commimications network, the method comprising: 

obtaining a description document via peer-to-peer networking firom the 

remote computing device, the description document defining a service-specific 

protocol involving an exchange of data messages via peer-to-peer networking 

connectivity with the remote computing device for controUing the logical device 

service on the remote computing device; 
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based on the description document, dynamically generating an instance of a 
programmatic interface for invocation by the client program to initiate service- 
specific operations for remote control of the logical device service; 

on invocation of the method members by the client program, translating the 
5 client program's programmatic interface invocation into the exchange of data 
messages via peer-to-peer networking connectivity in accordance with the 
description document for effecting control of the logical device service. 

9. The computer-readable medium of claim 8 wherein the programmatic 
10 interface is an object integration interface of an object-oriented programming model. 

1 0. The computer-readable medium of claim 8 wherein the data messages 
are in a mark-up language and exchanged via a hypertext transport protocol. 

15 11. The computer-readable medium of claim 8 wherein the service- 

specific operations include invoking commands of the service, querying a state of 
the service, and receiving and responding to events of the service. 

12, The computer-readable medium of claim 8 wherein the service has a 
20 set of properties defining a state of the service, and the service-specific operations 
include querying and setting values of the set of properties. 
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